1 | ================================================================================ |
---|
2 | ================================================================================ |
---|
3 | Protocol for geovis render server. |
---|
4 | |
---|
5 | Commands take the general form of command and arguments using Tcl syntax and are |
---|
6 | terminated by a newline. Some command arguments expect a Tcl list which can be |
---|
7 | sent by enclosing the list in curly braces to prevent the interpreter from |
---|
8 | splitting the list into multiple arguments. Likewise, strings with spaces |
---|
9 | should be quoted or enclosed in curly braces. In the documentation below, |
---|
10 | arguments are indicated by angle brackets and optional arguments are surrounded |
---|
11 | by question marks -- the brackets and question marks are not part of the |
---|
12 | protocol and should not be included in argument strings. The arguments shown |
---|
13 | in angle brackets should be replaced with a string (where there are fixed |
---|
14 | choices this document indicates valid values by separating them with pipe |
---|
15 | symbols), a list in Tcl syntax, or a numeric value. Boolean arguments can take |
---|
16 | the form of 0|1, true|false, or yes|no. Since the protocol commands are |
---|
17 | executed in a Tcl interpreter, Tcl code such as math expressions in expr |
---|
18 | commands enclosed in square brackets are also allowed. Since the interpreter |
---|
19 | is a "safe" interpreter, some Tcl commands that could cause security issues may |
---|
20 | not be available for use. |
---|
21 | |
---|
22 | When binary data is to be sent, it should follow the newline after a command |
---|
23 | that indicates incoming data including a byte count argument. |
---|
24 | ================================================================================ |
---|
25 | ================================================================================ |
---|
26 | Requests: |
---|
27 | ================================================================================ |
---|
28 | |
---|
29 | == General scene and renderer commands == |
---|
30 | |
---|
31 | camera delete <name> |
---|
32 | Delete named viewpoint |
---|
33 | camera dist <distance> |
---|
34 | Set camera distance from focal point |
---|
35 | camera extent <xmin> <ymin> <xmax> <ymax> <?duration?> <?srs?> |
---|
36 | Zoom to extent. Will fit the extent to the vertical FOV and center on |
---|
37 | the extent centroid. |
---|
38 | <xmin>,<ymin>,<xmax>,<ymax> = extent bounds in the specified SRS, |
---|
39 | or in the map's SRS if none is specified. |
---|
40 | <duration> = Duration of viewpoint move animation in seconds |
---|
41 | <srs> = The SRS of the extent bounds |
---|
42 | camera get |
---|
43 | Request camera parameters |
---|
44 | camera go <x> <y> <?zoomFactor?> <?duration?> |
---|
45 | Move camera to new focal point. |
---|
46 | <x>,<y> = Screen/mouse coordinates |
---|
47 | <zoomFactor> = Zoom distance multiplier, 1.0=no zoom |
---|
48 | <duration> = Duration of viewpoint move animation in seconds |
---|
49 | camera lextent <layerName> <?duration?> |
---|
50 | Zoom to layer extent. Will fit the extent to the vertical FOV and center |
---|
51 | on the extent centroid. |
---|
52 | <layerName> = Name of layer to use for extent. |
---|
53 | <duration> = Duration of viewpoint move animation in seconds |
---|
54 | camera orient <quatW> <quatX> <quatY> <quatZ> |
---|
55 | Set scene orientation using a quaternion |
---|
56 | camera pan <x> <y> |
---|
57 | <x,y> viewport coordinates (window center at 0,0). Positive x pan |
---|
58 | means pan object to right (camera to left). Positive y pan means |
---|
59 | pan object down (camera up). For example a pan of 0.5, 0.5 would |
---|
60 | move the object center to the lower right corner of the window |
---|
61 | camera reset <?all?> |
---|
62 | Option all resets orientation/rotation as well as pan/zoom/clip range |
---|
63 | camera restore <name> <?duration?> |
---|
64 | Set viewpoint to a named viewpoint, with optional animation duration in |
---|
65 | seconds |
---|
66 | camera rotate <x> <y> |
---|
67 | Specify relative rotation in viewport coordinates |
---|
68 | camera save <name> |
---|
69 | Save current viewpoint to a named viewpoint |
---|
70 | camera set <x> <y> <z> <heading> <pitch> <distance> <?duration?> <?srs?> <?vertDatum?> |
---|
71 | Explicitly set camera parameters, with optional animation duration in |
---|
72 | seconds |
---|
73 | <x>, <y> = Map coordinates of focal point |
---|
74 | <z> = Altitude of focal point (see vertDatum) |
---|
75 | <heading> = Azimuth in degrees |
---|
76 | <pitch> = Elevation in degrees |
---|
77 | <distance> = Distance of camera from focal point in map units(?) |
---|
78 | <srs> = coordinate system, defaults to map coordinate system |
---|
79 | <vertDatum> = vertical datum for interpreting z coordinate |
---|
80 | camera throw <bool> |
---|
81 | Enable/disable throw inertia for panning/rotating when using mouse events |
---|
82 | through protocol |
---|
83 | camera zoom <y> |
---|
84 | Specify zoom by viewport coordinates (i.e. normalized y mouse coords) |
---|
85 | |
---|
86 | clientinfo <list> |
---|
87 | |
---|
88 | colormap add <colorMapName> <colorMap> |
---|
89 | (Re-)define a colormap. If colorMapName doesn't exist, it is created, |
---|
90 | otherwise the colormap is redefined and all users will be updated. |
---|
91 | colorMap = Tcl list of {value r g b a} control points |
---|
92 | colormap define <colorMapName> <colorMap> |
---|
93 | (Re-)define a colormap (same as 'add') |
---|
94 | colormap delete <?colorMapName?> |
---|
95 | colormap res <numberOfTableEntries> |
---|
96 | Set the "resolution" or number of lookup table entries in the colormap |
---|
97 | <numberOfTableEntries> = integer or "default" |
---|
98 | |
---|
99 | legend <colormapName> <w> <h> <?opaque?> <?bgR?> <?bgG?> <?bgB?> |
---|
100 | Render a legend colorbar. |
---|
101 | <colormapName> - Name of the colormap defined with the colormap command |
---|
102 | <w>,<h> - width and height of colorbar |
---|
103 | <opaque> - If false, blend with background color |
---|
104 | <bgR>,<bgG>,<bgB> - Background color (defaults to black) |
---|
105 | |
---|
106 | renderer render |
---|
107 | Force a new image to be rendered |
---|
108 | |
---|
109 | screen bgcolor <r> <g> <b> |
---|
110 | screen coords <token> <coordList> <?srs?> <?verticalDatum?> |
---|
111 | Transate map coordinates to screen/mouse coordinates. |
---|
112 | <token> - String token, included in response |
---|
113 | <coordList> - A list of x,y,z map coordinates. If <srs> is not given, |
---|
114 | these are in the map's coordinate system. |
---|
115 | <srs> - Optional horizontal srs init string for coordinate system of |
---|
116 | x,y,z |
---|
117 | <verticalDatum> - Optional vertical srs init string for coordinate system |
---|
118 | of x,y,z |
---|
119 | screen size <width> <height> |
---|
120 | |
---|
121 | == Mouse and Keyboard Events == |
---|
122 | |
---|
123 | key press <key> |
---|
124 | key release <key> |
---|
125 | |
---|
126 | mouse click <button> <x> <y> |
---|
127 | mouse dblclick <button> <x> <y> |
---|
128 | mouse drag <button> <x> <y> |
---|
129 | mouse motion <x> <y> |
---|
130 | mouse release <button> <x> <y> |
---|
131 | mouse scroll <direction> |
---|
132 | |
---|
133 | == Interaction Configuration == |
---|
134 | |
---|
135 | placard config <attrlist> <textStyle> <bgR> <bgG> <bgB> <bgA> <padding> <layerName> |
---|
136 | <attrlist> - List of attributes. The list should consist of alternating attribute names and attribute labels. The names are the column names of the attributes in the feature data and the corresponding labels will be displayed on the info placard |
---|
137 | <textStyle> - CSS style attributes for TextSymbol |
---|
138 | <bgR>,<bgG>,<bgB>,<bgA> - RGBA color (floats [0,1]) for backdrop quad. |
---|
139 | <padding> - Pixels of padding between text and edge of backdrop quad. |
---|
140 | <layerName> - The name of the layer containing the feature data. |
---|
141 | |
---|
142 | == Map Commands == |
---|
143 | |
---|
144 | map attrib <string> |
---|
145 | <string> - Attribution/copyright to display in corner of map |
---|
146 | |
---|
147 | map coords <token> <coordList> <?srs?> <?verticalDatum?> |
---|
148 | Translate screen/mouse coordinates into map coordinates. |
---|
149 | <token> - String token, included in response |
---|
150 | <coordList> - A list of x,y screen/mouse coordinates |
---|
151 | <srs> - Optional horizontal srs init string for coordinate system to return |
---|
152 | <verticalDatum> - Optional vertical srs init string for coordinate system to |
---|
153 | return |
---|
154 | |
---|
155 | map grid <bool> <?type?> |
---|
156 | Toggle graticule and set type |
---|
157 | <type> = geodetic|utm|mgrs |
---|
158 | |
---|
159 | General form: |
---|
160 | map layer add <layerName> <type> <driver> <?url?> <?cache?> ... |
---|
161 | <type> = image|elevation|feature|icon|line|point|polygon|text |
---|
162 | <driver> = arcgis|colorramp|db|debug|gdal|ogr|tfs|tms|wcs|wfs|wms|xyz |
---|
163 | <cache> = bool indicating if tiles should be cached on disk |
---|
164 | |
---|
165 | Specific image layer types: |
---|
166 | map layer add <layerName> image colorramp <url> <cache> <coverage> <elevdriver> <profile> <colormapName> |
---|
167 | Add a colormapped image layer from a file or URL |
---|
168 | <url> = URL of source |
---|
169 | <cache> = bool indicating if tiles should be cached on disk |
---|
170 | <coverage> = bool indicating if data should not be interpolated (true means |
---|
171 | no interpolation) |
---|
172 | <elevdriver> = Elevation driver to read source |
---|
173 | <profile> = profile of source |
---|
174 | <colormapName> = Name of colormap |
---|
175 | map layer add <layerName> image arcgis <url> <?cache?> <?coverage?> <?token?> <?layers?> |
---|
176 | Add an ArcGIS MapServer image layer from a URL |
---|
177 | <url> = URL of source |
---|
178 | <cache> = bool indicating if tiles should be cached on disk |
---|
179 | <coverage> = bool indicating if data should not be interpolated (true means |
---|
180 | no interpolation) |
---|
181 | <token> = login credential |
---|
182 | map layer add <layerName> image gdal <url> <?cache?> <?coverage?> |
---|
183 | Add a GDAL image layer from a file or URL |
---|
184 | <url> = URL of source |
---|
185 | <cache> = bool indicating if tiles should be cached on disk |
---|
186 | <coverage> = bool indicating if data should not be interpolated (true means |
---|
187 | no interpolation) |
---|
188 | map layer add <layerName> image wms <url> <cache> <coverage> <layers> <format> <transparent> |
---|
189 | Add a WMS image layer from a URL + layer string |
---|
190 | <url> = URL of WMS service |
---|
191 | <cache> = bool indicating if tiles may be cached on disk |
---|
192 | <coverage> = bool indicating if data should not be interpolated (true means |
---|
193 | no interpolation) |
---|
194 | <layers> = layers string for WMS server |
---|
195 | <format> = Image format to return (e.g. 'png') |
---|
196 | <transparent> = bool |
---|
197 | map layer add <layerName> image tms <url> <cache> <coverage> |
---|
198 | Add a TMS image layer from a URL |
---|
199 | <url> = URL of TMS service |
---|
200 | <cache> = bool indicating if tiles should be cached on disk |
---|
201 | <coverage> = bool indicating if data should not be interpolated (true means |
---|
202 | no interpolation) |
---|
203 | map layer add <layerName> image xyz <urlPattern> <cache> <coverage> |
---|
204 | Add an image layer from a web map using a template URL |
---|
205 | <urlPattern> = URL template of source. '{x}', '{y}', '{z}' will be replaced |
---|
206 | with tile row (x), column (y) and zoom level (z). A block of characters in |
---|
207 | square braces can be used to specify round-robin server numbers, e.g. |
---|
208 | 'host[012]' will exand to 'host0', host1', 'host2'. |
---|
209 | <cache> = bool indicating if tiles should be cached on disk |
---|
210 | <coverage> = bool indicating if data should not be interpolated (true means |
---|
211 | no interpolation) |
---|
212 | |
---|
213 | Elevation layers: |
---|
214 | map layer add <layerName> elevation <driver> <url> <?cache?> |
---|
215 | Add an elevation image layer from a file or URL |
---|
216 | <driver> = gdal|tms|wcs |
---|
217 | |
---|
218 | Feature/model layers: |
---|
219 | In the following: |
---|
220 | <driver> = db|ogr|tfs|wfs |
---|
221 | <url> = file/web service address, or for driver 'db' the postgis connection string |
---|
222 | <format> = json|gml (for tfs or wfs driver) |
---|
223 | <typeName> = layer name for db or wfs driver |
---|
224 | <clamping> = none|terrain|relative|absolute |
---|
225 | <clamptechnique> = drape|gpu|scene|map |
---|
226 | |
---|
227 | map layer add <layerName> feature <driver> <format> <typeName> <url> <cache> <style> <?scripts?> <?selectors?> <?visibilityRangeMin?> <?visibilityRangeMax?> |
---|
228 | <style> = CSS styles (see http://docs.osgearth.org/en/latest/user/features.html and http://docs.osgearth.org/en/latest/references/symbology.html) |
---|
229 | <scripts> = JavaScript (see references above) |
---|
230 | <selectors> = List of name/value pairs |
---|
231 | map layer add <layerName> icon <driver> <format> <typeName> <url> <cache> <icon> <scale> <heading> <declutter> <placement> <alignment> <?visibilityRangeMin?> <?visibilityRangeMax?> |
---|
232 | Add an icon feature layer from a file or URL |
---|
233 | <placement> = vertex|centroid|interval|random |
---|
234 | <alignment> = left_top|left_center|left_bottom|center_top|center_center|center_bottom|right_top|right_center|right_bottom |
---|
235 | map layer add <layerName> line <driver> <format> <typeName> <url> <cache> <r> <g> <b> <width> <?cap?> <?join?> <?stipplePattern?> <?stippleFactor?> <?clamping?> <?clamptechnique?> <?visibilityRangeMin?> <?visibilityRangeMax?> |
---|
236 | Add a line feature layer from a file or URL |
---|
237 | cap/join only used if width > 1 |
---|
238 | <cap> = flat|square|round |
---|
239 | <join> = mitre|round |
---|
240 | map layer add <layerName> point <driver> <format> <typeName> <url> <cache> <r> <g> <b> <size> <?clamping?> <?clamptechnique?> <?visibilityRangeMin?> <?visibilityRangeMax?> |
---|
241 | Add a point feature layer from a file or URL |
---|
242 | map layer add <layerName> polygon <driver> <format> <typeName> <url> <cache> <r> <g> <b> <?lineWidth?> <?strokeR?> <?strokeG?> <?strokeB?> <?clamping?> <?clamptechnique?> <?visibilityRangeMin?> <?visibilityRangeMax?> |
---|
243 | Add a polygon feature layer from a file or URL |
---|
244 | map layer add <layerName> text <driver> <format> <typeName> <url> <cache> <content> <priority> <fgR> <fgG> <fgB> <bgR> <bgG> <bgB> <haloWidth> <fontSize> <removeDupes> <declutter> <alignment> <xoffset> <yoffset> <?visibilityRangeMin?> <?visibilityRangeMax?> |
---|
245 | Add a text symbol layer from a file or URL |
---|
246 | <alignment> = left_top|left_center|left_bottom|center_top|center_center|center_bottom|right_top|right_center|right_bottom|left_baseline|center|baseline|right_baseline|left_bottom_baseline|center_bottom_baseline|right_bottom_baseline |
---|
247 | |
---|
248 | map layer delete <layerName> |
---|
249 | map layer opacity <opacity> <layerName> |
---|
250 | map layer move <pos> <layerName> |
---|
251 | map layer visible <bool> <layerName> |
---|
252 | |
---|
253 | map load data follows <nbytes> |
---|
254 | Send an .earth file over the wire |
---|
255 | map load file <path> |
---|
256 | Load an .earth file from a filesystem mounted on the server |
---|
257 | map load url <url> |
---|
258 | Load an .earth file from a network address |
---|
259 | |
---|
260 | map posdisp <bool> <?format?> <?precision?> |
---|
261 | Toggle coordinate/position display, set format and precision |
---|
262 | <format> = latlong_decimal_degrees|latlong_degrees_decimal_minutes| |
---|
263 | latlong_degrees_minutes_seconds|mgrs |
---|
264 | <precision> = integer number of digits to display |
---|
265 | |
---|
266 | map reset <type> <r> <g> <b> <?profile?> <?xmin?> <?ymin?> <?xmax?> <?ymax?> |
---|
267 | Clear the scene and rebuild a new map from scratch. When resetting the |
---|
268 | map to geocentric, a profile and extents should be omitted. When the map |
---|
269 | type is projected, the profile is required and extents are optional. |
---|
270 | <type> = geocentric|projected |
---|
271 | <r>,<g>,<b> - Background color red, green and blue components [0,1] |
---|
272 | <profile> = Well known profile string, e.g. 'global-geodetic', |
---|
273 | 'global-mercator'. If specifying bounds (i.e. not global), use 'geodetic' |
---|
274 | or 'spherical-mercator' or an SRS init string (such as an EPSG code) |
---|
275 | xmin,ymin,xmax,ymax = map bounds (in profile projection/units) |
---|
276 | |
---|
277 | map scalebar <bool> <?units?> |
---|
278 | Toggle scale label/bar |
---|
279 | <units> = meters|feet|us_survey_feet|nautical_miles |
---|
280 | map setpos <x> <y> |
---|
281 | Set the coordinate/position display based on mouse coordinates |
---|
282 | map terrain edges <bool> |
---|
283 | *Not currently implemented* |
---|
284 | map terrain lighting <bool> |
---|
285 | map terrain linecolor <r> <g> <b> |
---|
286 | *Not currently implemented* |
---|
287 | map terrain vertscale <val> |
---|
288 | Set scale factor for terrain height |
---|
289 | map terrain wireframe <bool> |
---|
290 | map time <?hours?> <?day?> <?month?> <?year?> |
---|
291 | Set ephemeris time for sky. When args are omitted, set to current time. |
---|
292 | Time is interpreted as UTC. |
---|
293 | |
---|
294 | ================================================================================ |
---|
295 | Replies: |
---|
296 | ================================================================================ |
---|
297 | nv>image -type image -bytes <nbytes> |
---|
298 | <binary RGB data> |
---|
299 | nv>legend <colormapName> <rmin> <rmax> <nbytes> |
---|
300 | <binary RGB data> |
---|
301 | nv>map coords <token> <mapCoordList> <?srs?> <?verticalDatum?> |
---|
302 | Reply to query of map coordinates from screen coordinates. The mapCoordList |
---|
303 | is a list of x,y,z map coordinates. The srs of the map coordinates may be |
---|
304 | included if not in map's native coordinate system. NaN in the results |
---|
305 | indicates off-map input coordinates. |
---|
306 | nv>screen coords <token> <screenCoordList> |
---|
307 | Reply to query of screen coordinates from map coordinates. The |
---|
308 | screenCoordList is a list of x,y,z screen coordinates (z is the depth). NaN |
---|
309 | in the results indicates a point outside the view frustum or invalid input |
---|
310 | map coordinate |
---|
311 | nv>ok -token <seqnum> |
---|
312 | Reply indicated commands through <seqnum> (numbered beginning at 0) have been |
---|
313 | processed, but no new image was rendered |
---|
314 | ================================================================================ |
---|
315 | Error Replies: |
---|
316 | ================================================================================ |
---|
317 | nv>viserror -bytes <nbytes> |
---|
318 | <multi-line error string of nbytes> |
---|
319 | ================================================================================ |
---|