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

Last change on this file since 4790 was 4098, checked in by ldelgass, 10 years ago

update protocol doc

  • 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
99<flowObj> configure <?option value...?>
100          -ambient <val>
101          -arrows <bool>
102          -axis <x|y|z>
103          -diffuse <val>
104          -hide <bool>
105          -light2side <bool>
106          -opacity <val>
107          -outline <bool>
108          -position <val|%val>
109           val = world coordinate, or %val = [0,100]
110          -slice <bool>
111          -specularExp <val>
112          -specularLevel <val>
113          -transferfunction <name>
114          -volume <bool>
115<flowObj> data follows <nbytes> <numComponents>
116          Send flow data.  Data bytes follow the newline after the command
117<flowObj> legend <w> <h>
118
119<flowObj> particles add <name> <?switches?>
120          see '<flowObj> particles configure' for switches
121<flowObj> particles configure <name> <?switches?>
122          -axis <x|y|z>
123          -color <{r g b a}>
124          -hide <bool>
125          -position <val|%val>
126           val = [0,100], or %val = [0,1]
127          -size <val>
128<flowObj> particles delete <names>
129<flowObj> particles names
130          This doesn't currently produce a response, it only returns a Tcl list
131          within the server's interpreter
132
133grid axiscolor <red> <green> <blue> <?alpha?>
134grid axisname <x|y|z> <name> <units>
135grid linecolor <red> <green> <blue> <?alpha?>
136grid visible <bool>
137
138heightmap create <heightmapName> <xMin> <yMin> <xMax> <yMax> <xNum> <yNum> <valueList>
139heightmap cull <none|back|front>
140heightmap data follows <nBytes> <heightmapName>
141          After newline following command, nBytes of data are sent
142heightmap data visible <bool> <?heightmapNames?>
143heightmap legend <heightmapName> <width> <height>
144heightmap linecontour color <red> <green> <blue> <?heightmapNames?>
145heightmap linecontour visible <bool> <?heightmapNames?>
146heightmap opacity <value> <?heightmapNames?>
147heightmap polygon <wireframe|fill>
148          **Warning: This is a global setting**
149heightmap shading <flat|smooth>
150          **Warning: This is a global setting**
151heightmap transfunc <transferFunctionName> <?heightmapNames?>
152
153legend <transferfunc name> <width> <height>
154       Request render of transfer function
155
156screen bgcolor <r> <g> <b>
157       Set screen background color
158screen size <width> <height>
159       Set size of rendered images
160
161snapshot
162         Render a 2k x 2k image (offscreen buffer). Response image data is tagged
163         as '-type print'
164
165transfunc define <name> {colors} {alpha}
166          colors => 1 line each of "value r g b"
167          alpha => 1 line each of "value alpha"
168          value => [0,1]
169
170up <x|y|z|-x|-y|-z>
171   Set orientation of volumes
172
173volume animation capture <numframes> <?filename?>
174       This is not fully implemented.  Rendered frames are not returned
175       to the client.
176volume animation clear
177volume animation start
178volume animation stop
179volume animation volumes <?names?>
180
181volume data follows <nbytes> <name>
182volume data state <bool> <?names?>
183volume delete <names>
184volume exists <name>
185       This doesn't currently produce a response, it only returns a boolean
186       within the server's interpreter
187volume names
188       This doesn't currently produce a response, it only returns a Tcl list
189       within the server's interpreter
190volume outline color <r> <g> <b> <?names?>
191volume outline state <bool> <?names?>
192volume outline visible <bool> <?names?>
193volume shading ambient <value> <?names?>
194volume shading diffuse <value> <?names?>
195volume shading isosurface <bool> <?names?>
196volume shading light2side <bool> <?names?>
197volume shading opacity <value> <?names?>
198volume shading specularExp <value> <?names?>
199volume shading specularLevel <value> <?names?>
200volume shading transfunc <tfName> <?names?>
201volume state <bool> <?names?>
202
203================================================================================
204Replies:
205================================================================================
206nv>legend <volume> <min> <max> <nbytes>
207  (followed by bytes)
208
209nv>image -type image -bytes <nbytes>
210  (followed by bytes)
211
212nv>image -type print -bytes <nbytes>
213  (followed by bytes)
214
215nv>image -type movie -token <token> -bytes <nbytes>
216  (followed by bytes)
217
218nv>data tag <dataobj-tag> min <val> max <val> vmin <val> vmax <val>
219   The min,max data values for the data object and the cumulative volume data
220   min,max over all volumes
221
222nv>data tag <flow-tag> min <val> max <val>
223   Sent after a "<flowObj> data follows...".  Min,max values are for the
224   magnitude of the vector field.
225
226================================================================================
227Error Replies:
228================================================================================
229nv>viserror -bytes <nbytes>
230   <multi-line error string of nbytes>
231================================================================================
Note: See TracBrowser for help on using the repository browser.