source: geovis/trunk/geovis_protocol.txt @ 4973

================================================================================
================================================================================
Protocol for geovis render server.  

Commands take the general form of command and arguments using Tcl syntax and are
terminated by a newline.  Some command arguments expect a Tcl list which can be
sent by enclosing the list in curly braces to prevent the interpreter from 
splitting the list into multiple arguments.  Likewise, strings with spaces 
should be quoted or enclosed in curly braces.  In the documentation below,
arguments are indicated by angle brackets and optional arguments are surrounded
by question marks -- the brackets and question marks are not part of the
protocol and should not be included in argument strings.  The arguments shown 
in angle brackets should be replaced with a string (where there are fixed 
choices this document indicates valid values by separating them with pipe 
symbols), a list in Tcl syntax, or a numeric value.  Boolean arguments can take
the form of 0|1, true|false, or yes|no.  Since the protocol commands are 
executed in a Tcl interpreter, Tcl code such as math expressions in expr 
commands enclosed in square brackets are also allowed.  Since the interpreter
is a "safe" interpreter, some Tcl commands that could cause security issues may 
not be available for use.

When binary data is to be sent, it should follow the newline after a command 
that indicates incoming data including a byte count argument.
================================================================================
================================================================================
Requests:
================================================================================

== General scene and renderer commands ==

camera delete <name>
       Delete named viewpoint
camera dist <distance>
       Set camera distance from focal point
camera get
       Request camera parameters
camera go <x> <y> <?zoomFactor?> <?duration?>
       Move camera to new focal point.
       <x>,<y> = Screen/mouse coordinates
       <zoomFactor> = Zoom distance multiplier, 1.0=no zoom
       <duration> = Duration of viewpoint move animation in seconds
camera orient <quatW> <quatX> <quatY> <quatZ>
       Set scene orientation using a quaternion
camera pan <x> <y>
       <x,y> viewport coordinates (window center at 0,0).  Positive x pan
       means pan object to right (camera to left).  Positive y pan means
       pan object down (camera up).  For example a pan of 0.5, 0.5 would
       move the object center to the lower right corner of the window
camera reset <?all?>
       Option all resets orientation/rotation as well as pan/zoom/clip range
camera restore <name> <?duration?>
       Set viewpoint to a named viewpoint, with optional animation duration in 
       seconds
camera rotate <x> <y>
       Specify relative rotation in viewport coordinates
camera save <name>
       Save current viewpoint to a named viewpoint
camera set <x> <y> <z> <heading> <pitch> <distance> <?duration?> <?srs?> <?vertDatum?>
       Explicitly set camera parameters, with optional animation duration in 
       seconds
       <x>, <y> = Map coordinates of focal point
       <z> = Altitude of focal point (see vertDatum)
       <heading> = Azimuth in degrees
       <pitch> = Elevation in degrees
       <distance> = Distance of camera from focal point in map units(?)
       <srs> = coordinate system, defaults to map coordinate system
       <vertDatum> = vertical datum for interpreting z coordinate 
camera throw <bool>
       Enable/disable throw inertia for panning/rotating when using mouse events
       through protocol
camera zoom <y>
       Specify zoom by viewport coordinates (i.e. normalized y mouse coords)

clientinfo <list>

colormap add <colorMapName> <colorMap> <opacityMap>
         (Re-)define a colormap.  If colorMapName doesn't exist, it is created,
         otherwise the colormap is redefined and all users will be updated.
         colorMap = Tcl list of {value r g b} control points
         opacityMap = Tcl list of {value alpha} control points
colormap define <colorMapName> <colorMap> <opacityMap>
         (Re-)define a colormap (same as 'add')
colormap delete <?colorMapName?>
colormap res <numberOfTableEntries>
         Set the "resolution" or number of lookup table entries in the colormap
         <numberOfTableEntries> = integer or "default"

renderer render
         Force a new image to be rendered

screen bgcolor <r> <g> <b>
screen coords <token> <coordList> <?srs?> <?verticalDatum?>
       Transate map coordinates to screen/mouse coordinates.
       <token> - String token, included in response
       <coordList> - A list of x,y,z map coordinates.  If <srs> is not given,
       these are in the map's coordinate system.
       <srs> - Optional horizontal srs init string for coordinate system of 
       x,y,z
       <verticalDatum> - Optional vertical srs init string for coordinate system
       of x,y,z
screen size <width> <height>

== Mouse and Keyboard Events ==

key press <key>
key release <key>

mouse click <button> <x> <y>
mouse dblclick <button> <x> <y>
mouse drag <button> <x> <y>
mouse motion <x> <y>
mouse release <button> <x> <y>
mouse scroll <direction>

== Map Commands ==

map coords <token> <coordList> <?srs?> <?verticalDatum?>
    Translate screen/mouse coordinates into map coordinates.
    <token> - String token, included in response
    <coordList> - A list of x,y screen/mouse coordinates
    <srs> - Optional horizontal srs init string for coordinate system to return
    <verticalDatum> - Optional vertical srs init string for coordinate system to
    return

map grid <bool> <?type?>
    Toggle graticule and set type
    <type> = geodetic|utm|mgrs

General form:
map layer add <type> <driver> <url> ... <layerName>
    <type> = image|elevation|line|point|polygon|text
    <driver> = gdal|tms|wms|xyz

Specific image layer types:
map layer add image gdal <url> <cache> <layerName>
    Add a GDAL image layer from a file or URL
map layer add image wms <url> <cache> <layers> <format> <transparent> <layerName>
    Add a WMS image layer from a URL + layer string
    <url> = URL of WMS service
    <cache> = bool indicating if tiles should be cached on disk
    <layers> = layers string for WMS server
    <format> = Image format to return (e.g. 'png')
    <transparent> = bool
map layer add image tms <url> <cache> <layerName>
    Add a TMS image layer from a URL
    <url> = URL of TMS service
    <cache> = bool indicating if tiles should be cached on disk
map layer add image xyz <urlPattern> <cache> <layerName>
    Add an image layer from a web map using a template URL
    <cache> = bool indicating if tiles should be cached on disk

Elevation layers:
map layer add elevation <driver> <url> <layerName>
    Add an elevation image layer from a file or URL
    <driver> = gdal|tms|wms

Feature/model layers:
map layer add point <url> <layerName>
    Add a point feature layer from a file or URL
map layer add polygon <url> <layerName>
    Add a polygon feature layer from a file or URL
map layer add line <url> <layerName>
    Add a line feature layer from a file or URL
map layer add text <url> <layerName>
    Add a text symbol layer from a file or URL

map layer delete <layerName>
map layer opacity <opacity> <layerName>
map layer move <pos> <layerName>
map layer visible <bool> <layerName>

map load data follows <nbytes>
    Send an .earth file over the wire
map load file <path>
    Load an .earth file from a filesystem mounted on the server
map load url <url>
    Load an .earth file from a network address

map posdisp <bool> <?format?> <?precision?>
    Toggle coordinate/position display, set format and precision
    <format> = latlong_decimal_degrees|latlong_degrees_decimal_minutes|
               latlong_degrees_minutes_seconds|mgrs
    <precision> = integer number of digits to display

map reset <type> <?profile?> <?xmin?> <?ymin?> <?xmax?> <?ymax?>
    Clear the scene and rebuild a new map from scratch.  When resetting the 
    map to geocentric, a profile and extents should be omitted.  When the map
    type is projected, the profile is required and extents are optional.
    type = geocentric|projected
    profile = Well known profile string, e.g. 'global-geodetic',
    'global-mercator'.  If specifying bounds (i.e. not global), use 'geodetic'
    or 'spherical-mercator' or an SRS init string (such as an EPSG code)
    xmin,ymin,xmax,ymax = map bounds (in profile projection/units)

map scalebar <bool> <?units?>
    Toggle scale label/bar
    <units> = meters|feet|us_survey_feet|nautical_miles
map setpos <x> <y>
    Set the coordinate/position display based on mouse coordinates
map terrain edges <bool>
    *Not currently implemented*
map terrain lighting <bool>
map terrain linecolor <r> <g> <b>
    *Not currently implemented*
map terrain vertscale <val>
    Set scale factor for terrain height
map terrain wireframe <bool>
map time <?hours?> <?day?> <?month?> <?year?>
    Set ephemeris time for sky.  When args are omitted, set to current time.
    Time is interpreted as server's local time.

================================================================================
Replies:
================================================================================
nv>image -type image -bytes <nbytes>
  <binary RGB data>
nv>map coords <token> <mapCoordList> <?srs?> <?verticalDatum?>
   Reply to query of map coordinates from screen coordinates.  The mapCoordList
   is a list of x,y,z map coordinates.  The srs of the map coordinates may be 
   included if not in map's native coordinate system.  NaN in the results 
   indicates off-map input coordinates.
nv>screen coords <token> <screenCoordList>
   Reply to query of screen coordinates from map coordinates.  The
   screenCoordList is a list of x,y,z screen coordinates (z is the depth).  NaN
   in the results indicates a point outside the view frustum or invalid input
   map coordinate
nv>ok -token <seqnum>
   Reply indicated commands through <seqnum> (numbered beginning at 0) have been
   processed, but no new image was rendered
================================================================================
Error Replies:
================================================================================
nv>viserror -bytes <nbytes>
   <multi-line error string of nbytes>
================================================================================