source: geovis/trunk/geovis_protocol.txt @ 5119

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

Add legend option for blending against a background color

File size: 11.3 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>
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 a} control points
80colormap define <colorMapName> <colorMap>
81         (Re-)define a colormap (same as 'add')
82colormap delete <?colorMapName?>
83colormap res <numberOfTableEntries>
84         Set the "resolution" or number of lookup table entries in the colormap
85         <numberOfTableEntries> = integer or "default"
86
87legend <colormapName> <w> <h> <?opaque?> <?bgR?> <?bgG?> <?bgB?>
88       Render a legend colorbar.
89       <colormapName> - Name of the colormap defined with the colormap command
90       <w>,<h> - width and height of colorbar
91       <opaque> - If false, blend with background color
92       <bgR>,<bgG>,<bgB> - Background color (defaults to black)
93
94renderer render
95         Force a new image to be rendered
96
97screen bgcolor <r> <g> <b>
98screen coords <token> <coordList> <?srs?> <?verticalDatum?>
99       Transate map coordinates to screen/mouse coordinates.
100       <token> - String token, included in response
101       <coordList> - A list of x,y,z map coordinates.  If <srs> is not given,
102       these are in the map's coordinate system.
103       <srs> - Optional horizontal srs init string for coordinate system of
104       x,y,z
105       <verticalDatum> - Optional vertical srs init string for coordinate system
106       of x,y,z
107screen size <width> <height>
108
109== Mouse and Keyboard Events ==
110
111key press <key>
112key release <key>
113
114mouse click <button> <x> <y>
115mouse dblclick <button> <x> <y>
116mouse drag <button> <x> <y>
117mouse motion <x> <y>
118mouse release <button> <x> <y>
119mouse scroll <direction>
120
121== Map Commands ==
122
123map attrib <string>
124    <string> - Attribution/copyright to display in corner of map
125
126map coords <token> <coordList> <?srs?> <?verticalDatum?>
127    Translate screen/mouse coordinates into map coordinates.
128    <token> - String token, included in response
129    <coordList> - A list of x,y screen/mouse coordinates
130    <srs> - Optional horizontal srs init string for coordinate system to return
131    <verticalDatum> - Optional vertical srs init string for coordinate system to
132    return
133
134map grid <bool> <?type?>
135    Toggle graticule and set type
136    <type> = geodetic|utm|mgrs
137
138General form:
139map layer add <layerName> <type> <driver> <url> ...
140    <type> = image|elevation|line|point|polygon|text
141    <driver> = colorramp|debug|gdal|tms|wms|xyz
142
143Specific image layer types:
144map layer add <layerName> image colorramp <url> <cache> <elevdriver> <profile> <colormapName>
145    Add a colormapped image layer from a file or URL
146    <url> = URL of source
147    <cache> = bool indicating if tiles should be cached on disk
148    <elevdriver> = Elevation driver to read source
149    <profile> = profile of source
150    <colormapName> = Name of colormap
151map layer add <layerName> image gdal <url> <cache>
152    Add a GDAL image layer from a file or URL
153map layer add <layerName> image wms <url> <cache> <layers> <format> <transparent>
154    Add a WMS image layer from a URL + layer string
155    <url> = URL of WMS service
156    <cache> = bool indicating if tiles should be cached on disk
157    <layers> = layers string for WMS server
158    <format> = Image format to return (e.g. 'png')
159    <transparent> = bool
160map layer add <layerName> image tms <url> <cache>
161    Add a TMS image layer from a URL
162    <url> = URL of TMS service
163    <cache> = bool indicating if tiles should be cached on disk
164map layer add <layerName> image xyz <urlPattern> <cache>
165    Add an image layer from a web map using a template URL
166    <cache> = bool indicating if tiles should be cached on disk
167
168Elevation layers:
169map layer add <layerName> elevation <driver> <url>
170    Add an elevation image layer from a file or URL
171    <driver> = gdal|tms|wms
172
173Feature/model layers:
174map layer add <layerName> point <url> <r> <g> <b> <size>
175    Add a point feature layer from a file or URL
176map layer add <layerName> polygon <url> <r> <g> <b> <width>
177    Add a polygon feature layer from a file or URL
178map layer add <layerName> line <url> <r> <g> <b> <width>
179    Add a line feature layer from a file or URL
180map layer add <layerName> text <url> <content> <priority> <fgR> <fgG> <fgB> <bgR> <bgG> <bgB> <haloWidth> <fontSize> <removeDupes> <declutter> <visibilityRangeMin> <visibilityRangeMax>
181    Add a text symbol layer from a file or URL
182
183map layer delete <layerName>
184map layer opacity <opacity> <layerName>
185map layer move <pos> <layerName>
186map layer visible <bool> <layerName>
187
188map load data follows <nbytes>
189    Send an .earth file over the wire
190map load file <path>
191    Load an .earth file from a filesystem mounted on the server
192map load url <url>
193    Load an .earth file from a network address
194
195map posdisp <bool> <?format?> <?precision?>
196    Toggle coordinate/position display, set format and precision
197    <format> = latlong_decimal_degrees|latlong_degrees_decimal_minutes|
198               latlong_degrees_minutes_seconds|mgrs
199    <precision> = integer number of digits to display
200
201map reset <type> <r> <g> <b> <?profile?> <?xmin?> <?ymin?> <?xmax?> <?ymax?>
202    Clear the scene and rebuild a new map from scratch.  When resetting the
203    map to geocentric, a profile and extents should be omitted.  When the map
204    type is projected, the profile is required and extents are optional.
205    <type> = geocentric|projected
206    <r>,<g>,<b> - Background color red, green and blue components [0,1]
207    <profile> = Well known profile string, e.g. 'global-geodetic',
208    'global-mercator'.  If specifying bounds (i.e. not global), use 'geodetic'
209    or 'spherical-mercator' or an SRS init string (such as an EPSG code)
210    xmin,ymin,xmax,ymax = map bounds (in profile projection/units)
211
212map scalebar <bool> <?units?>
213    Toggle scale label/bar
214    <units> = meters|feet|us_survey_feet|nautical_miles
215map setpos <x> <y>
216    Set the coordinate/position display based on mouse coordinates
217map terrain edges <bool>
218    *Not currently implemented*
219map terrain lighting <bool>
220map terrain linecolor <r> <g> <b>
221    *Not currently implemented*
222map terrain vertscale <val>
223    Set scale factor for terrain height
224map terrain wireframe <bool>
225map time <?hours?> <?day?> <?month?> <?year?>
226    Set ephemeris time for sky.  When args are omitted, set to current time.
227    Time is interpreted as UTC.
228
229================================================================================
230Replies:
231================================================================================
232nv>image -type image -bytes <nbytes>
233  <binary RGB data>
234nv>legend <colormapName> <rmin> <rmax> <nbytes>
235  <binary RGB data>
236nv>map coords <token> <mapCoordList> <?srs?> <?verticalDatum?>
237   Reply to query of map coordinates from screen coordinates.  The mapCoordList
238   is a list of x,y,z map coordinates.  The srs of the map coordinates may be
239   included if not in map's native coordinate system.  NaN in the results
240   indicates off-map input coordinates.
241nv>screen coords <token> <screenCoordList>
242   Reply to query of screen coordinates from map coordinates.  The
243   screenCoordList is a list of x,y,z screen coordinates (z is the depth).  NaN
244   in the results indicates a point outside the view frustum or invalid input
245   map coordinate
246nv>ok -token <seqnum>
247   Reply indicated commands through <seqnum> (numbered beginning at 0) have been
248   processed, but no new image was rendered
249================================================================================
250Error Replies:
251================================================================================
252nv>viserror -bytes <nbytes>
253   <multi-line error string of nbytes>
254================================================================================
Note: See TracBrowser for help on using the repository browser.