source: trunk/packages/vizservers/vtkvis/protocol.txt @ 3110

================================================================================
================================================================================
Protocol for vtkvis 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.

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:
================================================================================
screen bgcolor <r> <g> <b>
screen size <width> <height>

renderer clipplane <axis> <ratio> <direction>
         Set a user clipping plane, ratio is [0,1] and is always interpreted as
         0 = min_bound, 1 = max_bound, regardless of direction.  Sign of 
         direction determines normal of clipping plane.  User clip planes do not
         apply if camera mode is image.
renderer depthpeel <bool>
         Set use of depth peeling algorithm for transparency
renderer light2side <bool>
         Toggle use of two-sided lighting (controls if backfaces are lit with a
         flipped normal)
renderer render
         Force a new image to be rendered - use for advancing animation

axis color <r> <g> <b>
     Set color of axis lines, labels, titles, ticks
axis flymode <mode>
     <mode> = static_edges|static_triad|outer_edges|furthest_triad|closest_triad
axis grid <axis> <bool>
     <axis> = x|y|z|all
axis labels <axis> <bool>
     Toggle visibility of axis labels
     <axis> = x|y|z|all
axis name <axis> <title>
axis tickpos <position>
     Set position of ticks on 3D axes (not implemented for 2D axes)
     <position> = inside|outside|both
axis ticks <axis> <bool>
     Toggle visibility of axis tick marks
     <axis> = x|y|z|all
axis units <axis> <units>
     Currently only supported when camera mode is not image mode
axis visible <axis> <bool>
     <axis> = x|y|z|all
     Note: 'all' means all enabled axes.  To force all axes on, set each axis on
     individually -- however, it is best to let the server determine which of 
     the individual axes are enabled based on the dataset bounds.

camera get
       Request current camera parameters
camera mode <mode>
       <mode> = persp|ortho|image
camera orient <quatW> <quatX> <quatY> <quatZ>
       Set scene orientation using a quaternion
camera ortho <coordMode> <x> <y> <width> <height>
       <coordMode> = pixel|world
       Supply bounds of plot area for image camera mode
camera pan <x> <y>
       <x,y> viewport coordinates (window center at 0,0).  Positive x pan
       means pan object to right (camera to left).  Positive y pan means
       pan object down (camera up).  For example a pan of 0.5, 0.5 would
       move the object center to the lower right corner of the window
camera reset <?all?>
       Option all resets orientation/rotation as well as pan/zoom/clip range
camera rotate <yaw> <pitch> <roll>
       Specify relative rotation in Euler angles
camera set <posX> <posY> <posZ> <focalPtX> <focalPtY> <focalPtZ> <viewUpX> <viewUpY> <viewUpZ>
       Set camera parameters: camera position, focal point and view up vector
camera zoom <z>
       Specify zoom ratio.  z > 1 is a zoom in, z < 1 is zoom out. z = 1
       resets to default.

colormap add <colorMapName> <colorMap> <opacityMap>
         colorMap = Tcl list of {value r g b} control points
         opacityMap = Tcl list of {value alpha} control points
colormap delete <?colorMapName?>

legend <colormapName> <legendType> <fieldName> <legendTitle> <width> <height> <numLabels> <?datasetName?>
       Causes legend to be rendered and written back with labels and title
       (title may be left blank)
       <legendType> = scalar|vmag|vx|vy|vz
       <numLabels> Can be zero or more 'tick' value labels
       If datasetName is omitted, the cumulative data range of all data sets 
       will be used to label the legend -- otherwise, the current setting of 
       'dataset maprange' will be used to determine if the individual dataset
       range or cumulative range will be used.

dataset add <datasetName> data follows <nbytes>
dataset color <r> <g> <b> <?datasetName?>
        Set color of outline bounding box
dataset delete <?datasetName?>
dataset getscalar world <x> <y> <z> <datasetName>
dataset getscalar pixel <x> <y> <datasetName>
dataset getvector world <x> <y> <z> <datasetName>
dataset getvector pixel <x> <y> <datasetName>
        Use pixel for image camera mode
dataset maprange <val>
        <val> = all|visible|separate
        Controls if data range for colormapping and contours is based on
        cumulative range of all datasets ("all"), only visible datasets
        ("visible") or each individual dataset ("separate").  Defaults to
        "all"
dataset opacity <val> <?datasetName?>
dataset outline <bool> <?datasetName?>
        Toggle wireframe outline of dataset's bounding box
dataset scalar <scalarName> <?datasetName?>
        Set the active scalar field to plot
dataset vector <vectorName> <?datasetName?>
        Set the active vector field to plot
dataset visible <bool> <?datasetName?>

contour2d add numcontours <n> <?datasetName?>
          Generate evenly spaced contours including range endpoints.  See also
          'dataset maprange' command.
contour2d add contourlist <list> <?datasetName?>
          list = {isoval1 isoval2 isoval3...}
contour2d color <r> <g> <b> <?datasetName?>
          synonym for linecolor
contour2d delete <?datasetName?>
contour2d lighting <bool> <?datasetName?>
contour2d linecolor <r> <g> <b> <?datasetName?>
          synonym for color
contour2d linewidth <val> <?datasetName?>
contour2d opacity <val> <?datasetName?>
contour2d orient <qw> <qx> <qy> <qz> <?dataSetName?>
contour2d pos <x> <y> <z> <?dataSetName?>
contour2d scale <sx> <sy> <sz> <?dataSetName?>
contour2d visible <bool> <?datasetName?>

contour3d add numcontours <n> <?datasetName?>
          Generate evenly spaced contours including range endpoints.  See also
          'dataset maprange' command.
contour3d add contourlist <list> <?datasetName?>
          list = {isoval1 isoval2 isoval3...}
contour3d ccolor r g b <?datasetName?>
contour3d colormap <colorMapName> <?dataSetName?>
contour3d delete <?datasetName?>
contour3d edges <bool> <?datasetName?>
contour3d lighting <bool> <?datasetName?>
contour3d linecolor <r> <g> <b> <?datasetName?>
contour3d linewidth <val> <?datasetName?>
contour3d opacity <val> <?datasetName?>
contour3d orient <qw> <qx> <qy> <qz> <?dataSetName?>
contour3d pos <x> <y> <z> <?dataSetName?>
contour3d scale <sx> <sy> <sz> <?dataSetName?>
contour3d visible <bool> <?datasetName?>
contour3d wireframe <bool> <?datasetName?>

cutplane add <?dataSetName?>
cutplane axis <axis> <bool> <?dataSetName?>
         Toggle visibility of the 3 principal axis cutplanes
cutplane ccolor r g b <?datasetName?>
         Set color of outline bounding box
cutplane colormap <colorMapName> <?dataSetName?>
cutplane colormode <scalar|vmag|vx|vy|vz> <fieldName> <?datasetName?>
         Set the field used to color the object.  'scalar' uses
         the active scalar field.  'vmag' uses the magnitude of the current
         vector field, and 'vx','vy','vz' use the corresponding component of
         the active vector field.
cutplane delete <?dataSetName?>
cutplane edges <bool> <?dataSetName?>
cutplane lighting <bool> <?dataSetName?>
cutplane linecolor <r> <g> <b> <?dataSetName?>
cutplane linewidth <width> <?dataSetName?>
cutplane opacity <value> <?dataSetName?>
cutplane orient <qw> <qx> <qy> <qz> <?dataSetName?>
cutplane outline <bool> <?dataSetName?>
         Toggle rendering of cutplane outlines
cutplane pos <x> <y> <z> <?dataSetName?>
cutplane scale <sx> <sy> <sz> <?dataSetName?>
cutplane slice axis ratio <?dataSetName?>
         For 3D data, select a slice along a principle axis of the volume. The
         ratio is [0,1]
cutplane visible <bool> <?dataSetName?>
cutplane wireframe <bool> <?datasetName?>

glyphs add <shape> <?dataSetName?>
       See 'glyphs shape' for list of shapes
glyphs ccolor r g b <?datasetName?>
glyphs colormap <colorMapName> <?dataSetName?>
glyphs colormode <scalar|vmag|vx|vy|vz|ccolor> <fieldName> <?dataSetName?>
       Set the color mode: color by scalar field or
       vector magnitude -- uses the current color map,
       or ccolor for constant color
glyphs delete <?dataSetName?>
glyphs edges <bool> <?datasetName?>
glyphs gorient <bool> <fieldName> <?datasetName?>
       Set the glyph orientation mode: orient glyphs by
       a named vector field, or set to default orientation (off)
glyphs gscale <scaleFactor> <?datasetName?>
       Set glyph scaling factor
glyphs lighting <bool> <?datasetName?>
glyphs linecolor <r> <g> <b> <?datasetName?>
glyphs linewidth <val> <?datasetName?>
glyphs normscale <bool> <?datasetName?>
       Control if data values are normalized to [0,1] range before applying
       glyph scaling factor (gscale)
glyphs opacity <val> <?datasetName?>
glyphs orient <qw> <qx> <qy> <qz> <?dataSetName?>
glyphs pos <x> <y> <z> <?dataSetName?>
glyphs scale <sx> <sy> <sz> <?dataSetName?>
glyphs shape <arrow|cone|cube|cylinder|dodecahedron|icosahedron|line|octahedron|sphere|tetrahedron> <?datasetName?>
glyphs smode <scalar|vmag|vcomp|off> <fieldName> <?dataSetName?>
       Set the scaling mode: use the scalar field, vector magnitude 
       (uniform scale), vector components, or disable scaling
glyphs visible <bool> <?datasetName?>
glyphs wireframe <bool> <?datasetName?>

heightmap add numcontours <n> <heightScale> <?dataSetName?>
          Generate evenly spaced contours including range endpoints.  See also
          'dataset maprange' command.
heightmap add contourlist <list> <heightScale> <?dataSetName?>
          list = {isoval1 isoval2 isoval3...}
heightmap colormap <colorMapName> <?dataSetName?>
heightmap contourlist <list> <?dataSetName?>
heightmap delete <?dataSetName?>
heightmap edges <bool> <?dataSetName?>
heightmap heightscale <value> <?dataSetName?>
heightmap isolinecolor <r> <g> <b> <?dataSetName?>
heightmap isolines <bool> <?dataSetName?>
heightmap isolinewidth <width> <?dataSetName?>
heightmap lighting <bool> <?dataSetName?>
heightmap linecolor <r> <g> <b> <?dataSetName?>
heightmap linewidth <width> <?dataSetName?>
heightmap numcontours <n> <?dataSetName?>
heightmap opacity <value> <?dataSetName?>
heightmap orient <qw> <qx> <qy> <qz> <?dataSetName?>
heightmap pos <x> <y> <z> <?dataSetName?>
heightmap scale <sx> <sy> <sz> <?dataSetName?>
heightmap slice <axis> <ratio> <?dataSetName?>
          For 3D data, select a slice along a principle axis of the volume. The
          ratio is [0,1]
heightmap surface <bool> <?dataSetName?>
          Toggle rendering of colormapped surface (mountain plot or cutplane)
heightmap visible <bool> <?dataSetName?>
heightmap wireframe <bool> <?datasetName?>

lic add <?datasetName?>
lic colormap <colormapName> <?datasetName?>
lic delete <?datasetName?>
lic edges <bool> <?datasetName?>
lic lighting <bool> <?datasetName?>
lic linecolor <r> <g> <b> <?datasetName?>
lic linewidth <val> <?datasetName?>
lic opacity <val> <?datasetName?>
lic orient <qw> <qx> <qy> <qz> <?dataSetName?>
lic pos <x> <y> <z> <?dataSetName?>
lic scale <sx> <sy> <sz> <?dataSetName?>
lic slice <axis> <ratio> <?datasetName?>
    For 3D data, select a slice along a principle axis of the volume. The
    ratio is [0,1]
lic visible <bool> <?datasetName?>

molecule add <?datasetName?>
molecule atoms <bool> <?datasetName?>
         Toggle rendering of atoms
molecule ascale <val> <?datasetName?>
         Set atom scale factor
molecule bonds <bool> <?datasetName?>
         Toggle rendering of bonds
molecule bscale <val> <?datasetName?>
         Set bond scale factor
molecule colormap <colormapName> <?datasetName?>
molecule delete <?datasetName?>
molecule edges <bool> <?datasetName?>
molecule lighting <bool> <?datasetName?>
molecule linecolor <r> <g> <b> <?datasetName?>
molecule linewidth <val> <?datasetName?>
molecule opacity <val> <?datasetName?>
molecule orient <qw> <qx> <qy> <qz> <?dataSetName?>
molecule pos <x> <y> <z> <?dataSetName?>
molecule rscale <val> <?dataSetName?>
         Atom radius scaling
         val = van_der_waals|covalent|atomic|none
molecule scale <sx> <sy> <sz> <?dataSetName?>
molecule visible <bool> <?datasetName?>
molecule wireframe <bool> <?datasetName?>

polydata add <?datasetName?>
polydata color <r> <g> <b> <?datasetName?>
polydata delete <?datasetName?>
polydata edges <bool> <?datasetName?>
polydata lighting <bool> <?datasetName?>
polydata linecolor <r> <g> <b> <?datasetName?>
polydata linewidth <val> <?datasetName?>
polydata opacity <val> <?datasetName?>
polydata orient <qw> <qx> <qy> <qz> <?dataSetName?>
polydata pos <x> <y> <z> <?dataSetName?>
polydata ptsize <size> <?dataSetName?>
polydata scale <sx> <sy> <sz> <?dataSetName?>
polydata visible <bool> <?datasetName?>
polydata wireframe <bool> <?datasetName?>

pseudocolor add <?datasetName?>
pseudocolor ccolor r g b <?datasetName?>
pseudocolor colormap <colormapName> <?datasetName?>
pseudocolor colormode <scalar|vmag|vx|vy|vz|ccolor> <fieldName> <?datasetName?>
            Set the field used to color the object.  'ccolor' means to use
            the constant color defined by the ccolor subcommand.  'scalar' uses
            the active scalar field.  'vmag' uses the magnitude of the current
            vector field, and 'vx','vy','vz' use the corresponding component of
            the active vector field.
pseudocolor delete <?datasetName?>
pseudocolor edges <bool> <?datasetName?>
pseudocolor lighting <bool> <?datasetName?>
pseudocolor linecolor <r> <g> <b> <?datasetName?>
pseudocolor linewidth <val> <?datasetName?>
pseudocolor opacity <val> <?datasetName?>
pseudocolor orient <qw> <qx> <qy> <qz> <?dataSetName?>
pseudocolor pos <x> <y> <z> <?dataSetName?>
pseudocolor scale <sx> <sy> <sz> <?dataSetName?>
pseudocolor visible <bool> <?datasetName?>
pseudocolor wireframe <bool> <?datasetName?>

streamlines add <?datasetName?>
streamlines ccolor <r> <g> <b> <?datasetName?>
            Set the constant color of streamlines used for color mode 'ccolor'
streamlines colormap <colormapName> <?datasetName?>
            Colormap used to color streamlines/tubes/ribbons by vector magnitude
streamlines colormode <scalar|vmag|vx|vy|vz|ccolor> <fieldName> <?datasetName?>
            Set the field used to color the streamlines.  'ccolor' means to use
            the constant color defined by the ccolor subcommand.  'scalar' uses
            the active scalar field.  'vmag' uses the magnitude of the current
            vector field, and 'vx','vy','vz' use the corresponding component of
            the active vector field.
streamlines delete <?datasetName?>
streamlines edges <bool> <?datasetName?>
            Turn on/off edges for tubes, ribbons
streamlines length <?datasetName?>
            Set maximum length in world coordinates of streamlines
streamlines lighting <bool> <?datasetName?>
streamlines linecolor <r> <g> <b> <?datasetName?>
            Set color of edges for tubes, ribbons (lines are colored by colormap)
streamlines lines <?datasetName?>
            Set rendering type to polylines
streamlines linewidth <val> <?datasetName?>
streamlines opacity <val> <?datasetName?>
streamlines orient <qw> <qx> <qy> <qz> <?dataSetName?>
streamlines pos <x> <y> <z> <?dataSetName?>
streamlines ribbons <width> <angle> <?datasetName?>
            Set rendering type to ribbons, width is minimum half-width, angle is
            degrees offset from normal orientation
streamlines scale <sx> <sy> <sz> <?dataSetName?>
streamlines seed color <r> <g> <b> <?datasetName?>
streamlines seed disk <centerX> <centerY> <centerZ> <normalX> <normalY> <normalZ> <radius> <innerRadius> <numPoints> <?dataSetName?>
            Create a disk seed area with optional hole, filled with randomly 
            placed points
streamlines seed fmesh <numPoints> data follows <nbytes> <?datasetName?>
            Fill a mesh supplied as a VTK data file with randomly placed points
streamlines seed fpoly <centerX> <centerY> <centerZ> <normalX> <normalY> <normalZ> <angle> <radius> <numSides> <numPoints> <?dataSetName?>
            Create a regular n-sided polygonal seed area filled with randomly 
            placed points
streamlines seed mesh data follows <nbytes> <?datasetName?>
            Use points of a mesh supplied as a VTK data file
streamlines seed numpts <?datasetName?>
            If seeds have been created using 'seed random' or 'seed fmesh', 
            this command can be used to change the number of randomly 
            distributed seeds
streamlines seed points <?datasetName?>
            Use points of the streamlines' dataset mesh
streamlines seed polygon <centerX> <centerY> <centerZ> <normalX> <normalY> <normalZ> <angle> <radius> <numSides> <?dataSetName?>
            Create seed points from vertices of a regular n-sided polygon
streamlines seed rake <startX> <startY> <startZ> <endX> <endY> <endZ> <numPoints> <?datasetName?>
streamlines seed random <numPoints> <?datasetName?>
            Fill the streamlines' dataset mesh with randomly placed points
streamlines seed visible <bool> <?datasetName?>
streamlines tubes <numSides> <radius> <?datasetName?>
            Set rendering type to tubes, numSides is number of sides of tubes,
            radius is minimum tube radius
streamlines visible <bool> <?datasetName?>

volume add <?datasetName?>
volume colormap <colorMapName> <?datasetName?>
volume delete <?datasetName?>
volume lighting <bool> <?datasetName?>
volume orient <qw> <qx> <qy> <qz> <?dataSetName?>
volume pos <x> <y> <z> <?dataSetName?>
volume quality <val> <?datasetName?>
       val = [0,1]
volume scale <sx> <sy> <sz> <?dataSetName?>
volume shading ambient <coeff> <?datasetName?>
volume shading diffuse <coeff> <?datasetName?>
volume shading specular <coeff> <power> <?datasetName?>
volume visible <bool> <?datasetName?>

================================================================================
Replies:
================================================================================
nv>camera set <posX> <posY> <posZ> <focalPtX> <focalPtY> <focalPtZ> <viewUpX> <viewUpY> <viewUpZ>
   Reply to "camera get"
nv>image -type image -bytes <nbytes>
  <binary RGB data>
nv>image -type image -bbox {x y w h} -bytes <nbytes>
  <binary RGB data>
  The bounding box of the 2D image camera zoom region is supplied
  Note: The bbox coordinates are in the form used by 'camera ortho world ...':
  x,y - world coordinate of lower left corner, w,h - width height in world coords
  This form is currently used only if the camera mode is set to 'image'.
nv>legend <colormapName> <title> <rmin> <rmax> <nbytes>
  <binary RGB data>
nv>dataset scalar world <x> <y> <z> <value> <dataSetName>
nv>dataset scalar pixel <x> <y> <value> <dataSetName>
nv>dataset vector world <x> <y> <z> <valueX> <valueY> <valueZ> <dataSetName>
nv>dataset vector pixel <x> <y> <valueX> <valueY> <valueZ> <dataSetName>

================================================================================
Error Replies:
================================================================================
Prefixed with "VtkVis Server Error: "
Currently not guaranteed to be on a single line
================================================================================