 |
 |
 |
 |
 |
 |
 |
 |
 |
|
|
|
||||||||
|
||||||||||
|
Digital Earth > TerravisionTM > User Guide > TerraVision's OAA API 9. TerraVision's OAA/JavaScript APIOAA OverviewSRI's Open Agent Architecture (OAA) is a framework for integrating a community of heterogeneous software agents in a distributed environment. An OAA agent is a software process that performs some task and can register its services with a specialized agent called the facilitator agent. The facilitator agent manages all agent interactions in order to solve a query. It makes decisions about which agents are available, what their capabilities are, and manages the use of these agents to solve the query.
The TerraVisionTM terrain visualization system has been instrumented to become an OAA agent. It can connect to a facilitator and advertise various capabilities for controlling itself. This means that any agent could request that TerraVisionTM perform some function, such as fly to a particular location. This query is sent to the facilitator which checks to see if there is a TerraVisionTM agent that can handle the request. If this is the case, then the request is sent to TerraVisionTM and it will perform the operation. For further information on the OAA, please refer to the OAA Home Page. API DescriptionAll agents communicate with the facilitator using the Interagent Communication Language (ICL). This is a prolog-like declarative language that is capable of representing natural language expressions. Whenever an agent connects to a facilitator it must advertise the various solvables (functions) that can be requested of it and the parameters that these solvables can accept. In order to control an agent, you must know this information. The rest of this page therefore defines the API that the TerraVisionTM OAA agent offers.All TerraVisionTM solvables take the form, terrain3d(<func>, <options>). That is, TerraVisionTM only advertises one solvable: terrain3d. The first parameter is used to give the name of a function and all of its parameters for TerraVisionTM to perform, for example, message("Hello World"). The second parameter is used to pass any option parameters for that function - this will often be empty. This approach of using a single advertised solvable (rather than advertising a separate solvable for each function) was chosen to better align with existing OAA methodologies. TerraVisionTM is providing a capability to control 3-D terrain and so this is the solvable that it exports. It is feasible that another terrain visualization program could be instrumented as an OAA agent and support the terrain3d solvable also. This capability is not TerraVisionTM specific. Targetting Specific TerraVision browsersBy default, when you send a terrain3d() OAA command to a facilitator, it will be solved by all currently running instances of TerraVision that are connected to that facilitator. If you want to send your command to only a specific instance, or set of instances, then you can use the optional id() argument and specify the appropriate IDs.For example, to send the resetview command to the TerraVision instance with the ID string "MyViewer", then you would issue the following OAA command: terrain3d(resetview,id('MyViewer')). You can specify a list of ID strings to send the command to multiple TerraVision instances, e.g. terrain3d(resetview,[id('MyViewer'),id('MyOtherViewer')]). You can find the OAA ID for an instance by using the getinfo() OAA function call. You can also use the -oaaid command line option to TerraVision to explicitly specify that instance's ID string. JavaScript APIUnder the Netscape plugin version of TerraVisionTM, it is possible to communicate with the plugin via JavaScript in your HTML page. The JavaScript API is essentially a wrapper to the OAA API, so these can be treated as the same. In order to access the JavaScript API from a web page, simply call the "cmd" method of the plugin with a string containing the OAA command to execute, e.g.
top.embed_name.cmd( "set('SHOW_WIREFRAME','TRUE')" )
API SpecificationThe following functions are documented in the following API specification. These functions constitute version 1.0 of the TerraVision ICL interface.
Function : flyto( X, Y, Z, Yaw, Pitch, Roll ) Optional Parameters : id() Description : The flyto function instructs TerraVision to fly to a specific geocentric coordinate and orientation. A geocentric coordinate is a point in 3-space that represents an (x, y, z) offset from the center of the planet in units of meters. Orientation is specified in terms of a (yaw, pitch, roll) tuple in units of radians. Example : terrain3d( flyto( 345961.1, -125476.3, 20450715.2, 0, -1.57, 0), [] ) See Also :
setview,
setview_gdc
Function : getinfo( Id, Host, Os, Arch, Procs, Res ) Optional Parameters : id() Description : This function will return various useful pieces of information about the current TerraVision instance and the machine that it is running on. This includes the ID string that can be used in the optional id() argument of any OAA command, the full hostname of the client, the operating system name and version number of the client, the name of the host architecture, and the number of processors. The final value is currently reserved for future use and is always set to zero. Example : terrain3d( getinfo( Id, Host, Os, Arch, Procs, Res ), [] ) Function : getview( X, Y, Z, Yaw, Pitch, Roll ) Optional Parameters : id() Description : This function will return the current viewpoint position and orientation for the 3-D viewer. Upon successful completion, the (X, Y, Z) tuple will be instantiated with the geocentric coordinate of the current viewpoint, while the (Yaw, Pitch, Roll) tuple will be instantiated with the yaw, pitch, and roll orientation values in units of radians. Example : terrain3d( getview( X, Y, Z, Yaw, Pitch, Roll ), [] ) See Also :
getview_gdc,
setview
Function : getview_gdc( Lat, Long, Elev ) Optional Parameters : id() Description : The getview_gdc function will return the current viewpoint location in geodetic (lat/long) coordinates. Upon successful completion, the (Lat, Long) pair will be instantiated with the latitude and longitude location in units of degrees, while the Elev value will be instantiated with the elevation of the viewpoint above the ellipsoid in units of meters. Example : terrain3d( getview_gdc( Lat, Long, Elev ), [] ) See Also :
getview_gdc,
setview
Function : loadmodel( Url ) Optional Parameters : id() Description : This function will load and display a new VRML or GeoVRML model. The Url parameter points to the .wrl file to be loaded. This can be an http URL or a localhost pathname. Example : terrain3d( loadmodel( "http://www.tvgeo.com/TileSets/Pyramids/benning.mout.model/model.wrl" ), [] ) See Also :
unloadmodel,
loadterrain
Function : loadterrain( Imagery, Elevation ) Optional Parameters : id() Description : This function will load and display a new terrain model. The Imagery and Elevation parameters are URLs to the TerraVision orthorectified image (OI) and elevation (DEM) datasets, and the Geoname parameter is the GeoSet name for the terrain, which should be the same as the string in the geo-name field of the imagery dataset's tiles.tspec file. Example : terrain3d( loadterrain( "http://www.tvgeo.com/TileSets/Pyramids/sfbay.oi", "http://www.tvgeo.com/TileSets/Pyramids/sfbay.dem" ), [] ) See Also :
unloadterrain
loadmodel
Function : message( Text ) Optional Parameters : id() Description : This function will display a textual message inside a dialog window. This dialog window is a child of the 3-D viewer, i.e. it is iconified when the 3-D viewer is iconified, etc. You can include escape sequences such as \n in the message string to format your text. Example : terrain3d( message( "Hello TerraVision\nHow Are You?" ), [] ) Function : move( Forward, Right, Up ) Optional Parameters : id(), noanim Description : Moves the current viewpoint in a viewer-based direction. This means moving forward/backward along the path that the viewer is facing, sliding left/right and up/down in a direction perpendicular to the forward direction. All values are in units of meters. By default, the viewpoint will fly to the new location. If you specify the optional parameter, noanim, then the viewpoint will simply jump to the new location. Example : terrain3d( move( -100, 0, 0 ), [noanim] ) Function : refresh Optional Parameters : id() Description : Refreshes TerraVision's display. This function is generally not required as TerraVision will update the display whenever appropriate. This function was originally included primarily as a simple function to test the operation of the OAA API. Example : terrain3d( refresh, [] ) Function : pathload( Url ) Optional Parameters : id() Description : Loads a flight path from the given file, replacing any already loaded path. The path can then be played by calling the pathplay command. A flight path file can be created from the full TerraVision application via the Paths menu. Example : terrain3d( pathload('C:/paths/space2sri.path'), [] ) See Also :
pathreset,
pathplay,
pathstop,
pathpause
Function : pathreset Optional Parameters : id() Description : Unloads any currently loaded flight path, frees all flight path memory, and deletes any animation timers. Use this call to unload a flight path. Example : terrain3d( pathreset, [] ) See Also :
pathload,
pathplay,
pathstop,
pathpause
Function : pathplay Optional Parameters : id() Description : Plays the currently loaded flight path, as loaded via the pathload call. Playback begins at the start of the flight path or, if the path was previously paused with the pathpause command, then playback begins at the paused point. Example : terrain3d( pathplay, [] ) See Also :
pathload,
pathreset,
pathstop,
pathpause
Function : pathstop Optional Parameters : id() Description : Stops any currently playing path. Any subsequent call to pathplay will start playback from the start of the flight path. Example : terrain3d( pathstop, [] ) See Also :
pathload,
pathreset,
pathplay,
pathpause
Function : pathpause Optional Parameters : id() Description : Stops any currently playing path. Any subsequent call to pathplay will start playback from the point at which the flight path was paused. Example : terrain3d( pathpause, [] ) See Also :
pathload,
pathreset,
pathplay,
pathstop
Function : resetview Optional Parameters : id() Description : Returns the user to the initial viewpoint. That is, the viewpoint that the user was placed at when they first opened the 3-D viewer. With respect to multiple datasets, the origin of the lowest priority (i.e. lowest resolution) dataset is used. Example : terrain3d( resetview, [] ) See Also :
setview
Function : rotate( Yaw, Pitch, Roll ) Optional Parameters : id(), noanim Description : This function will rotate the viewpoint in the 3-D viewer. This is a relative rotation, i.e. you rotate (Yaw, Pitch, Roll) relative to the viewer's current orientation. All angles are given in units of radians. By default, the viewpoint will be animated to the new orientation. If you specify the optional parameter, noanim, then the viewpoint will simply jump to the new orientation. Example : terrain3d( rotate( 3.1415, 0, 0 ), [] ) See Also :
setview
Function : set( Option, Value1, [Value2, [Value3] ] ) Optional Parameters : id() Description : This function is used to change a number of TerraVision's internal settings, including rendering options, navigation options, and behaviors. The basic model is that you specify the option you want to change, and then supply a value. The number of value parameters depends upon the option. Below is a table of currently supported options along with the number and type of arguments they accept. The Boolean type can be either '0', 'F', or 'FALSE' to represent a false state, or '1', 'T', 'TRUE' to represent a true state.
Example : terrain3d( set( 'SHOW_LIGHTING', 'TRUE' ), [] ) See Also :
setview_gdc,
getview
Function : setview( X, Y, Z, Yaw, Pitch, Roll ) Optional Parameters : id() Description : This function will set the current viewpoint for the 3-D viewer. You pass in the location using geocentric coordinates, an (X, Y, Z) coordinate where the units are meters. Orientation is specified using a (Yaw, Pitch, Roll) tuple where all units are in radians. Example : terrain3d( setview( 1115471 -4850898 3988141, 0, -1.57, 0 ), [] ) See Also :
setview_gdc,
getview
Function : setview_gdc( Lat, Long, Elev, Yaw, Pitch, Roll ) Optional Parameters : id() Description : This function will set the current viewpoint for the 3-D viewer using geodetic (latitude/longitude) coordinates. You pass in values for the (Lat, Long, Elev) coordinate, where Lat and Long are in degrees and Elev is elevation above the ellipsoid in meters. The (Yaw, Pitch, Roll) orientation is specified in units of radians. It is defined to be relative to the local reference plane at the specified location, i.e. a value of (0,0,0) will always orient you so that you are upright and facing due north; and a value of (0,-PI/2,0) will always orient you so that you are facing straight down. Example : terrain3d( setview_gdc( 57.7174 -3.286119 200000, 0, -1.57, 0), [] ) Function : stopmotion Optional Parameters : id() Description : The stopmotion function will stop any current camera animation that is currently playing in the 3-D viewer. The user can use the mouse buttons to induce forward and backward momentum - this function nulls that momentum and stops the viewpoint from moving. Example : terrain3d( stopmotion, [] ) Function : translate( X, Y, Z ) Optional Parameters : id(), noanim Description : This function will move the viewpoint in the 3-D viewer. This is a relative move in geocentric coordinate space, i.e. you move (X, Y, Z) from the current geocentric viewpoint position. By default, the viewpoint will be animated to the new location. If you specify the optional parameter, noanim, then the viewpoint will simply jump to the new location. Example : terrain3d( translate( 1000, 0, 200 ), [noanim] ) Function : unloadmodel( Url ) Optional Parameters : id() Description : This function will unload a currently loaded VRML/GeoVRML model from the viewer. The Url parameter should be the same as that used in order to load the model in the first place via the loadmodel command. Examples : terrain3d( unloadterrain( "http://www.tvgeo.com/TileSets/Pyramids/benning.mout.model/model.wrl" ), [] ) See Also :
loadmodel,
loadterrain
Function : unloadterrain( Geoname ) Optional Parameters : id() Description : This function will unload a current terrain model from the viewer. The Geoname parameter can be one of two things. It can be the URL that you specified for the OI dataset in the call to loadterrain(), or it can be the GeoSet name for the terrain you wish to unload. The GeoSet name is found under the geo-name field in the tiles.tspec file of the OI dataset. Examples : terrain3d( unloadterrain( "SF Bay Area" ), [] ) See Also : loadterrain, loadmodel
Copyright ©2000 SRI International. All rights reserved. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The figure on the right shows a monitor program (which is actually an
agent itself). This monitor shows the facilitator that it is connected
to, along with the set of all agents that are connected to that agent
(4 in this instance). All of these agents can be running on different,
heterogenous platforms and communicate with the facilitator using
TCP/IP over a network. One powerful feature of the OAA is that agents
can connect and disconnect from the OAA at will - the facilitator is
constantly aware of all available agents and if one agent disconnects
then this service is simply not available at that time.