source: geovis/trunk/geovis_protocol.txt @ 4629

Last change on this file since 4629 was 4629, checked in by ldelgass, 7 years ago

add token to map/screen coord commands

File size: 9.8 KB
Line 
1================================================================================
2================================================================================
3Protocol for geovis render server. 
4
5Commands take the general form of command and arguments using Tcl syntax and are
6terminated by a newline.  Some command arguments expect a Tcl list which can be
7sent by enclosing the list in curly braces to prevent the interpreter from
8splitting the list into multiple arguments.  Likewise, strings with spaces
9should be quoted or enclosed in curly braces.  In the documentation below,
10arguments are indicated by angle brackets and optional arguments are surrounded
11by question marks -- the brackets and question marks are not part of the
12protocol and should not be included in argument strings.  The arguments shown
13in angle brackets should be replaced with a string (where there are fixed
14choices this document indicates valid values by separating them with pipe
15symbols), a list in Tcl syntax, or a numeric value.  Boolean arguments can take
16the form of 0|1, true|false, or yes|no.  Since the protocol commands are
17executed in a Tcl interpreter, Tcl code such as math expressions in expr
18commands enclosed in square brackets are also allowed.  Since the interpreter
19is a "safe" interpreter, some Tcl commands that could cause security issues may
20not be available for use.
21
22When binary data is to be sent, it should follow the newline after a command
23that indicates incoming data including a byte count argument.
24================================================================================
25================================================================================
26Requests:
27================================================================================
28
29== General scene and renderer commands ==
30
31camera delete <name>
32       Delete named viewpoint
33camera dist <distance>
34       Set camera distance from focal point
35camera get
36       Request camera parameters
37camera go <x> <y> <?zoomFactor?> <?duration?>
38       Move camera to new focal point.
39       <x>,<y> = Screen/mouse coordinates
40       <zoomFactor> = Zoom distance multiplier, 1.0=no zoom
41       <duration> = Duration of viewpoint move animation in seconds
42camera orient <quatW> <quatX> <quatY> <quatZ>
43       Set scene orientation using a quaternion
44camera pan <x> <y>
45       <x,y> viewport coordinates (window center at 0,0).  Positive x pan
46       means pan object to right (camera to left).  Positive y pan means
47       pan object down (camera up).  For example a pan of 0.5, 0.5 would
48       move the object center to the lower right corner of the window
49camera reset <?all?>
50       Option all resets orientation/rotation as well as pan/zoom/clip range
51camera restore <name> <?duration?>
52       Set viewpoint to a named viewpoint, with optional animation duration in
53       seconds
54camera rotate <x> <y>
55       Specify relative rotation in viewport coordinates
56camera save <name>
57       Save current viewpoint to a named viewpoint
58camera set <x> <y> <z> <heading> <pitch> <distance> <?duration?> <?srs?> <?vertDatum?>
59       Explicitly set camera parameters, with optional animation duration in
60       seconds
61       <x>, <y> = Map coordinates of focal point
62       <z> = Altitude of focal point (see vertDatum)
63       <heading> = Azimuth in degrees
64       <pitch> = Elevation in degrees
65       <distance> = Distance of camera from focal point in map units(?)
66       <srs> = coordinate system, defaults to map coordinate system
67       <vertDatum> = vertical datum for interpreting z coordinate
68camera throw <bool>
69       Enable/disable throw inertia for panning/rotating when using mouse events
70       through protocol
71camera zoom <y>
72       Specify zoom by viewport coordinates (i.e. normalized y mouse coords)
73
74clientinfo <list>
75
76colormap add <colorMapName> <colorMap> <opacityMap>
77         (Re-)define a colormap.  If colorMapName doesn't exist, it is created,
78         otherwise the colormap is redefined and all users will be updated.
79         colorMap = Tcl list of {value r g b} control points
80         opacityMap = Tcl list of {value alpha} control points
81colormap define <colorMapName> <colorMap> <opacityMap>
82         (Re-)define a colormap (same as 'add')
83colormap delete <?colorMapName?>
84colormap res <numberOfTableEntries>
85         Set the "resolution" or number of lookup table entries in the colormap
86         <numberOfTableEntries> = integer or "default"
87
88renderer render
89         Force a new image to be rendered
90
91screen bgcolor <r> <g> <b>
92screen coords <token> <x> <y> <z> <?srs?> <?verticalDatum?>
93       Transate map coordinates to screen/mouse coordinates.
94       <token> - String token, included in response
95       <x>,<y>,<z> - Map coordinates.  If srs not given, these are in the map's
96       coordinate system.
97       <srs> - Optional horizontal srs init string for coordinate system of
98       x,y,z
99       <verticalDatum> - Optional vertical srs init string for coordinate system
100       of x,y,z
101screen size <width> <height>
102
103== Mouse and Keyboard Events ==
104
105key press <key>
106key release <key>
107
108mouse click <button> <x> <y>
109mouse dblclick <button> <x> <y>
110mouse drag <button> <x> <y>
111mouse motion <x> <y>
112mouse release <button> <x> <y>
113mouse scroll <direction>
114
115== Map Commands ==
116
117map coords <token> <x> <y> <?srs?> <?verticalDatum?>
118    Translate screen/mouse coordinates into map coordinates.
119    <token> - String token, included in response
120    <x>,<y> - Screen/mouse coordinates
121    <srs> - Optional horizontal srs init string for coordinate system to return
122    <verticalDatum> - Optional vertical srs init string for coordinate system to
123    return
124
125map grid <bool> <?type?>
126    Toggle graticule and set type
127    <type> = geodetic|utm|mgrs
128
129General form:
130map layer add <type> <driver> <url> ... <layerName>
131    <type> = image|elevation|line|point|polygon|text
132    <driver> = gdal|tms|wms|xyz
133
134Specific image layer types:
135map layer add image gdal <url> <layerName>
136    Add a GDAL image layer from a file or URL
137map layer add image wms <url> <layers> <format> <transparent> <layerName>
138    Add a WMS image layer from a URL + layer string
139    <url> = URL of WMS service
140    <layers> = layers string for WMS server
141    <format> = Image format to return (e.g. 'png')
142    <transparent> = bool
143map layer add image tms <url> <layerName>
144    Add a TMS image layer from a URL
145    <url> = URL of TMS service
146map layer add image xyz <urlPattern> <layerName>
147    Add an image layer from a web map using a template URL
148
149Elevation layers:
150map layer add elevation <driver> <url> <layerName>
151    Add an elevation image layer from a file or URL
152    <driver> = gdal|tms|wms
153
154Feature/model layers:
155map layer add point <url> <layerName>
156    Add a point feature layer from a file or URL
157map layer add polygon <url> <layerName>
158    Add a polygon feature layer from a file or URL
159map layer add line <url> <layerName>
160    Add a line feature layer from a file or URL
161map layer add text <url> <layerName>
162    Add a text symbol layer from a file or URL
163
164map layer delete <layerName>
165map layer opacity <opacity> <layerName>
166map layer move <pos> <layerName>
167map layer visible <bool> <layerName>
168
169map load data follows <nbytes>
170    Send an .earth file over the wire
171map load file <path>
172    Load an .earth file from a filesystem mounted on the server
173map load url <url>
174    Load an .earth file from a network address
175
176map posdisp <bool> <?format?> <?precision?>
177    Toggle coordinate/position display, set format and precision
178    <format> = latlong_decimal_degrees|latlong_degrees_decimal_minutes|
179               latlong_degrees_minutes_seconds|mgrs
180    <precision> = integer number of digits to display
181
182map reset <type> <?profile?> <?xmin?> <?ymin?> <?xmax?> <?ymax?>
183    Clear the scene and rebuild a new map from scratch.  When resetting the
184    map to geocentric, a profile and extents should be omitted.  When the map
185    type is projected, the profile is required and extents are optional.
186    type = geocentric|projected
187    profile = Well known profile string, e.g. 'global-geodetic',
188    'global-mercator'.  If specifying bounds (i.e. not global), use 'geodetic'
189    or 'spherical-mercator' or an SRS init string (such as an EPSG code)
190    xmin,ymin,xmax,ymax = map bounds (in profile projection/units)
191
192map scalebar <bool> <?units?>
193    Toggle scale label/bar
194    <units> = meters|feet|us_survey_feet|nautical_miles
195map setpos <x> <y>
196    Set the coordinate/position display based on mouse coordinates
197map terrain edges <bool>
198    *Not currently implemented*
199map terrain lighting <bool>
200map terrain linecolor <r> <g> <b>
201    *Not currently implemented*
202map terrain vertscale <val>
203    Set scale factor for terrain height
204map terrain wireframe <bool>
205
206================================================================================
207Replies:
208================================================================================
209nv>image -type image -bytes <nbytes>
210  <binary RGB data>
211nv>map coords <token> <mapX> <mapY> <mapZ> <screenX> <screenY> <?srs?> <?verticalDatum?>
212   Reply to query of map coordinates from screen coordinates.  srs of the map
213   coordinates may be included if not in map's native coordinate system
214nv>map coords <token> invalid <mouseX> <mouseY>
215   Reply indicating an off-map click/query
216nv>screen coords <token> <screenX> <screenY> <screenZ> <mapX> <mapY> <mapZ>
217   Reply to query of screen coordinates from map coordinates
218nv>screen coords <token> invalid <mapX> <mapY> <mapZ>
219   Reply indicating requested point is out of the view frustum
220nv>ok -token <seqnum>
221   Reply indicated commands through <seqnum> (numbered beginning at 0) have been
222   processed, but no new image was rendered
223================================================================================
224Error Replies:
225================================================================================
226nv>viserror -bytes <nbytes>
227   <multi-line error string of nbytes>
228================================================================================
Note: See TracBrowser for help on using the repository browser.