a note: i have many projects i'm currently working on, of which geov is only one. geov is still in a fast paced development stage with a single developer (me). thus, the sad truth is that documentation will always tend to lag behind implementation. so take these instructions with a grain of salt and if things seem inconsistent, please do not hesitate to email me with questions [tes at mit.edu]. i will answer them, i promise.
the google earth interface for ocean vehicles (geov) allows you to visualize the location of ocean craft. you can view positions of the vehicles as they are known (realtime) or visualize historical data of any known vehicles. it is highly configurable, allowing the user to visualize the current vehicle's location and a trail of its past position.
geov is comprised of this webpage interface (accessible from any web browser) and a script (kml) running in google earth. google earth is freely downloadable from http://earth.google.com/.
follow these steps to use geov (you may find the section "how does this work" useful as well):
geov stores all its data in a MySQL database. currently, two mechanisms exist for importing data. the first is a realtime tool (iMOOS2SQL) intended to interface a MOOS database containing AIS_REPORT variables (and other data, as needed for various modules) with the geov database. (for details on MOOS and MOOS-IvP, go to the authors' websites (Paul Newman, Mike Benjamin)).
iMOOS2SQL takes all AIS_REPORT variables (which are published primarily by pTransponderAIS) in the community it is run and imports them into the geov database specified in the .moos file at a maximum frequency of once per second. iMOOS2SQL is undergoing continued development, so anyone without access to the mit moos svn repository should contact the author (tes at mit.edu) for the latest version the second tool is available on this website "import .alog" and is used to import vehicle logs from pLogger, thereby allowing data that is inaccessible during operations to be viewed later in playback mode.
geov is not connected to the MOOS in any way beyond these import tools, thus making it possible to easily support data from other software systems. anyone interested in writing an import tool for a different source should contact the author (tes at mit.edu) for assistance.
go to the profile manager and create a user name (or log in with one you already have). profiles are grouped by user, but it is possible to make copies of profiles for other users. choose the type of profile you wish to create:
realtime: attempts to show vehicle position as recently as possible from the server's system clock. in this mode you are seeing what is happening right now.
playback: mimicks realtime, but for point in the past. this mode is like a video recorder playback.
history: gives the trails for specified vehicles that can be manipulated in google earth with the time slider. this mode is somewhat analogous to a video editing program.
once you have named your profile, you are in the profile editing screen. you should see a table of all the known vehicles. in order to see any vehicles in google earth, you must check at least one of the "show _" boxes.
available options (note that some options are not available for all modes:
show vehicle image: displays a graphic representing the vehicle on the map. image scale modifies the size of this image relative to the vehicle's real size.
show vehicle name: displays text with the vehicle's name on the map. this item maintains its size no matter the zoom level.
show points: show a trail of points with the position history of the vehicle. each point represents an update from the vehicle.
show lines: show the lines that interpolate between the update points. this is helpful for vehicles with infrequent updates.
color: the color of the objects for that vehicle.
trail decay: the time (in seconds) that the points or lines stay on the screen for. (that is, anything older than trail decay seconds ago is not displayed).
track: keep the current vehicle in view at all times (overrides the ability to free fly in google earth) if the track bubble is set to "all", the camera is freed again.
track follows vehicle's current heading: forces your view to point in the heading of the tracked vehicle.
on the profile manager page, you must either check the box for "use this machine's ip" or enter another ip if you wish to run google earth on a different machine from the one you are currently running the web page interface on. use /sbin/ifconfig on GNU/Linux or ipconfig in Windows to determine your ip address.
a given machine can only be bound to a single profile. if you change profiles and bind your machine again, all previous bindings are removed. this simply means you can only view one profile at a time for each machine running google earth. in practice, just ensure that you remember to see that the binding is set (checkbox is checked or ip values entered) for that profile in order to view it.
click the link on the navigation bar (called "download geov kml") to download the geov kml (keyhole markup language, which is google earth's data format) file. save it to your computer. open google earth, then use the file | open dialog to open the file you just downloaded (geov_core_{servername}.kml). please note that this file is specific to the server geov is running on, so you would need to download a new file for a cruise that is using a different server.
geov is now running in google earth. assuming you have completed the above steps, you should now see vehicles in the places pane (part of the bar on the left side). to zoom quickly to the part of the world of interest, double click the name of one of the vehicles to fly to that location.
for playback mode, you must launch the playback controls from the profile page. this will open a new web browser window which you may resize to your liking. the playback controls are much like a DVD player, etc. you must push play in order to see any vehicles in the view
for history mode, you will want to use the time slider within google earth to change what you see. you can also use the playback mode on that time slider. be sure to use the advanced options button next to the time slider to adjust playback speed and other useful options
no vehicles present in google earth: go to the profile manager and ensure that you have selected at least one vehicle for viewing ("show name, show image, etc") and that you have clicked save and refresh after doing so. also ensure that you have bound your ip to this profile (see above).
google earth gives me an error: this software is still in the development stage and thus some bugs are to be expected. use google earth's "ignore" or "continue" button in the error dialog and see if the error is resolved. if not, close google earth, wait at least ten seconds and reopen it. bug reports to tes at mit.edu are welcome.
profile manager: click "name", "type", or "owner" to sort (ascending) all the visible vehicles on the display.
use the boxes below the label "all" to make changes at once to all the visible vehicles.
google earth: use the tilt control (top slider in the upper right) to go to a 3D view of the world.
go to tools | options and change settings. try changing the fly-to speed under touring to 0.5. bump up the cache values to maximum in order to use google earth without an internet connection most effectively. google earth will cache areas you look at so if you want to use geov on a cruise without internet, simply zoom around the area you will be using while you have internet, then it will be available when you do not.
the basic functionality for geov is based on the ability for google earth to read in specially formatted xml files (kml) to display such things as lines, polygons, and images overlaid on specific latitudes / longitudes. one of the kml tags, NetworkLinkControl, causes google earth to query a specified webserver for a kml file to display. thus, the kml file you download and open in google earth only contains the code that forces google earth to query (every second) this webserver, which forms the other half of geov.
the webserver (apache2) is running php and mysql. php is a scripting language that can produce xml and html (or most any other desired output). mysql is a fast access database that interfaces with php (among other languages). thus, all the data for geov is stored in the mysql database (by iMOOS2SQL or a similar process). the profile manager stores information about what a given user wants to see, which modifies the output passed by php to google earth when it is queried. the ip address of the machine running google earth tells php which profile to use when determining which data to send.
(insert data flow diagram)