source: nanovis/trunk/protocol-nanovis.txt @ 5717

Last change on this file since 5717 was 4885, checked in by ldelgass, 9 years ago

Merge fixes from release branch

  • Property svn:eol-style set to native
File size: 8.8 KB
Line 
1================================================================================
2
3 Copyright (C) 2004-2013  HUBzero Foundation, LLC
4
5================================================================================
6Protocol for nanovis render server. 
7
8Commands take the general form of command and arguments using Tcl syntax and are
9terminated by a newline.  Some command arguments expect a Tcl list which can be
10sent by enclosing the list in curly braces to prevent the interpreter from
11splitting the list into multiple arguments.  Likewise, strings with spaces
12should be quoted or enclosed in curly braces.  In the documentation below,
13arguments are indicated by angle brackets and optional arguments are surrounded
14by question marks -- the brackets and question marks are not part of the
15protocol and should not be included in argument strings.  The arguments shown
16in angle brackets should be replaced with a string (where there are fixed
17choices this document indicates valid values by separating them with pipe
18symbols), a list in Tcl syntax, or a numeric value.  Boolean arguments can take
19the form of 0|1, true|false, or yes|no.  Since the protocol commands are
20executed in a Tcl interpreter, Tcl code such as math expressions in expr
21commands enclosed in square brackets are also allowed.  Since the interpreter
22is a "safe" interpreter, some Tcl commands that could cause security issues may
23not be available for use.
24
25Some commands such as the 'flowvis add' commands create Tcl objects within the
26server's interpreter.  The name sent as an argument when adding the object can
27then be used as a protocol command.  For example, the string sent as the <name>
28argument to 'flowvis add' can then be used in place of <flowObj> in the commands
29documented below.  The flow object name also creates a volume name that can
30be used in volume and cutplane commands, but in that case the name is used as
31an argument to the volume or cutplane commands rather than as the command
32itself.
33
34When binary data is to be sent, it should follow the newline after a command
35that indicates incoming data including a byte count argument.
36================================================================================
37================================================================================
38Requests:
39================================================================================
40axis visible <bool>
41
42camera angle <xAngle> <yAngle> <zAngle>
43       ** Deprecated, use camera orient **
44camera orient <quatW> <quatX> <quatY> <quatZ>
45camera pan <x> <y>
46camera pos <x> <y> <z>
47camera reset <?all?>
48camera zoom <factor>
49
50clientinfo <list>
51
52cutplane position <relval> <x|y|z> <?names?>
53         Set the position of a volume cutplane.  Names is
54         an optional list of volume names.
55         relval = [0,1]
56cutplane state <bool> <x|y|z> <?names?>
57         Set the axis (normal) of a volume cutplane.  Names is
58         an optional list of volume names.
59cutplane visible <bool> <?names?>
60         Set visibility of all (x,y, and z) cutplanes for
61         named volume(s)
62
63flow add <name> <?option value...?>
64         <name> is an object name to use in <flowObj> commands
65         In addition, a volume is added with the same name
66         which can be used in volume and cutplane commands
67         see '<flowObj> configure' for switch options
68flow delete <names>
69flow exists <name>
70     This doesn't currently produce a response, it only returns a boolean
71     within the server's interpreter
72flow goto <nSteps>
73flow names
74     This doesn't currently produce a response, it only returns a Tcl list
75     within the server's interpreter
76flow next
77flow reset
78flow video <token> <?switches...?>
79     -bitrate <val>
80     -format <mpeg|theora|mov>
81     -framerate <val>
82     -height <val>
83     -numframes <val>
84     -width <val>
85
86<flowObj> box add <name> <?switches...?>
87          See '<flowObj> box configure' for switches
88<flowObj> box configure <name> <?switches...?>
89         -color <{r g b a}>
90         -corner1 <{x y z}>
91         -corner2 <{x y z}>
92         -hide <bool>
93         -linewidth <val>
94<flowObj> box delete <names>
95<flowObj> box names
96          This doesn't currently produce a response, it only returns a Tcl list
97          within the server's interpreter
98<flowObj> configure <?option value...?>
99          -ambient <val>
100          -arrows <bool>
101          -axis <x|y|z>
102          -diffuse <val>
103          -hide <bool>
104          -light2side <bool>
105          -opacity <val>
106          -outline <bool>
107          -position <val|val%>
108           val = world coordinate, or val% = [0,100]
109          -slice <bool>
110          -specularExp <val>
111          -specularLevel <val>
112          -transferfunction <name>
113          -volume <bool>
114<flowObj> data follows <nbytes> <numComponents>
115          Send flow data.  Data bytes follow the newline after the command
116<flowObj> legend <w> <h>
117<flowObj> particles add <name> <?switches?>
118          see '<flowObj> particles configure' for switches
119<flowObj> particles configure <name> <?switches?>
120          -axis <x|y|z>
121          -color <{r g b a}>
122          -hide <bool>
123          -position <val|val%>
124           val = world coordinate, or val% = [0,100]
125          -size <val>
126<flowObj> particles delete <names>
127<flowObj> particles names
128          This doesn't currently produce a response, it only returns a Tcl list
129          within the server's interpreter
130
131grid axiscolor <red> <green> <blue> <?alpha?>
132grid axisname <x|y|z> <name> <units>
133grid linecolor <red> <green> <blue> <?alpha?>
134grid visible <bool>
135
136heightmap create <heightmapName> <xMin> <yMin> <xMax> <yMax> <xNum> <yNum> <valueList>
137heightmap cull <none|back|front>
138heightmap data follows <nBytes> <heightmapName>
139          After newline following command, nBytes of data are sent
140heightmap data visible <bool> <?heightmapNames?>
141heightmap legend <heightmapName> <width> <height>
142heightmap linecontour color <red> <green> <blue> <?heightmapNames?>
143heightmap linecontour visible <bool> <?heightmapNames?>
144heightmap opacity <value> <?heightmapNames?>
145heightmap polygon <wireframe|fill>
146          **Warning: This is a global setting**
147heightmap shading <flat|smooth>
148          **Warning: This is a global setting**
149heightmap transfunc <transferFunctionName> <?heightmapNames?>
150
151legend <transferfunc name> <width> <height>
152       Request render of transfer function
153
154screen bgcolor <r> <g> <b>
155       Set screen background color
156screen size <width> <height>
157       Set size of rendered images
158
159snapshot
160         Render a 2k x 2k image (offscreen buffer).  Response image data is
161         tagged as '-type print'
162
163transfunc define <name> {colors} {alpha}
164          colors => 1 line each of "value r g b"
165          alpha => 1 line each of "value alpha"
166          value => [0,1]
167
168up <x|y|z|-x|-y|-z>
169   Set orientation of volumes
170
171volume animation capture <numframes> <?filename?>
172       This is not fully implemented.  Rendered frames are not returned
173       to the client.
174volume animation clear
175volume animation start
176volume animation stop
177volume animation volumes <?names?>
178
179volume data follows <nbytes> <name>
180volume data state <bool> <?names?>
181volume delete <names>
182volume exists <name>
183       This doesn't currently produce a response, it only returns a boolean
184       within the server's interpreter
185volume names
186       This doesn't currently produce a response, it only returns a Tcl list
187       within the server's interpreter
188volume outline color <r> <g> <b> <?names?>
189volume outline state <bool> <?names?>
190volume outline visible <bool> <?names?>
191volume shading ambient <value> <?names?>
192volume shading diffuse <value> <?names?>
193volume shading isosurface <bool> <?names?>
194volume shading light2side <bool> <?names?>
195volume shading opacity <value> <?names?>
196volume shading specularExp <value> <?names?>
197volume shading specularLevel <value> <?names?>
198volume shading transfunc <tfName> <?names?>
199volume state <bool> <?names?>
200
201================================================================================
202Replies:
203================================================================================
204nv>legend <volume> <min> <max> <nbytes>
205  (followed by bytes)
206
207nv>image -type image -bytes <nbytes>
208  (followed by bytes)
209
210nv>image -type print -bytes <nbytes>
211  (followed by bytes)
212
213nv>image -type movie -token <token> -bytes <nbytes>
214  (followed by bytes)
215
216nv>data tag <dataobj-tag> min <val> max <val> vmin <val> vmax <val>
217   The min,max data values for the data object and the cumulative volume data
218   min,max over all volumes
219
220nv>data tag <flow-tag> min <val> max <val>
221   Sent after a "<flowObj> data follows...".  Min,max values are for the
222   magnitude of the vector field.
223
224================================================================================
225Error Replies:
226================================================================================
227nv>viserror -bytes <nbytes>
228   <multi-line error string of nbytes>
229================================================================================
Note: See TracBrowser for help on using the repository browser.