Watershed-Ocean Initiative: Base Software

Daily software releases of Watershed-Ocean Initiative are available for download from http://www.oworld.org/mp/code/. All downloads are archived in .zip files which are named woi_MonthDay.zip where MonthDay is the month and day the archive was created. Dates will be removed when they are no longer supported. The Watershed-Ocean Initiative application is currently a Java application being built with kind Open Source assistance from Java World Wind, JOGL - the Java Open Graphics Library, and PostgreSQL code communities. Please see their websites for more information.

Downloading Watershed-Ocean Initiative

Please download the latest .zip file using your favorite Web browser. Most browsers let you click on a Web link with your right mouse button and choose a download option (see the Firefox browser example here). We recommend downloading to your computer desktop initially. Consult your Web browser documentation for other ways to download files from a file directory residing on the World Wide Web.

Installing Watershed-Ocean Initiative

Please expand the .zip archive you downloaded from our Web-based repository. If you don't have decompression software installed on your system, consider using WinZip which is available here for Windows, or WinRAR for most popular operating systems (including Mac and other Linux flavors) here. When you expand the .zip archive, you should find four directories within the archive: bin, data, lib, and rivers. The bin directory includes our Watershed-Ocean Initiative code. The lib directory includes both the Java-based components and native Mac and Windows libraries for other code on which our code is based. The rivers directory includes the watershed datasets that have been prepared appropriately for this software (eventually the whole KML specification will be incorporated more flexibly). The data directory includes data layers you might want to explore locally and which will allow you to run locally without an Internet connection after you have cached the area of the planet on which you want to overlay.

You want to run Watershed-Ocean Initiative from a directory directly above the bin, data, lib, and rivers directories (meaning a directory (or folder) in which the bin, lib, and rivers directories are visible as directories (or folders). You can name that directory whatever you please, but make note of where it is on your system. Use your Java Runtime Environment (JRE) software to run our demonstration. Any version of Java 1.6 should work fine (the appropriate Java command to verify your Java run-time version is: java -version). You can run the Watershed-Ocean Initiative from within your Web browser through any link on our demonstrations page, but the latest version of the software is pre-loaded with some example data layers for the Narragansett Bay watershed of Rhode Island and Massachusetts, USA.

You can run the local version using Java from a command prompt in almost any computer terminal. Versions of Windows provide a command prompt through the cmd.exe executable (which means you can launch a command prompt from the Start menu - just click on Start, then Run and enter cmd in the dialog box that requests a program name). If cmd.exe is not on your system, try using command.exe instead. Versions of Mac OS X and other Linux flavors provide a command prompt through the Terminal application. Use your application finder to find Terminal on your non-Windows based system.

Once you have a command prompt available to you, change to the directory on your system where you have placed the bin, data, lib, and rivers folders. Use the cd command to change directories (see an example here). Typically, when you launch a command prompt, you launch it either in your Desktop directory of the directory above it. If you see you are already at your Desktop in the command prompt text that appears, you should be able to change to the directory on your Desktop where you put the Watershed-Ocean Initiative files. If you aren't at your Desktop, try going there with the command: cd Desktop. Then, change to your directory. For me, I run the command: cd woi because I put my bin and lib directories in a folder named woi on my Desktop. You can verify you are in the right directory from wiith in your command prompt. Either the ls or dir command (or both) should give you a listing of your files in the current directory.

Once you are in the right place, try launching Watershed-Ocean Initiative by using the appropriate Java command. For a Windows-based computer system, you likely will need to run the following command (the -mx flag opens 512 MB of memory to your Java runtime system; the -cp flag sets the classpath to pick up the other libraries the software requires; the -D flag points to java native libraries needed to operate your graphics hardware; the DemoMain class is currently the launch class within the software):

java -mx512m -cp bin;lib/BasicDemo.jar;lib/gluegen-rt.jar;lib/jogl.jar;lib/mysql-connector.jar -Djava.library.path=lib gov.nasa.worldwind.woi.DemoMain

For a Linux or Mac-based system (or both), you likely will need to run this command:

java -mx512m -cp ./bin:./lib/BasicDemo.jar:./lib/gluegen-rt.jar:./lib/jogl.jar:./lib/mysql-connector.jar -Djava.library.path=lib gov.nasa.worldwind.woi.DemoMain

If your Java runtime is not available from your directory, you will need to set an environment variable that points to your Java installation. Or, perhaps you don't have a Java runtime installed? You can get Java runtimes for free download from http://www.java.com/en/download/manual.jsp. Learn about environmental variables here.

Note that you don't have to type the Java command into your command prompt. Most command prompts let you use your system clipboard to transfer text from a Web page (like this one) to the command prompt. Highlight the command you want to use, click with your right mouse button on the highlight, choose Copy from the pop-up menu that appears, and then paste that command into your command prompt. Hit the return key on your keyboard to execute the Java command (and bring up the application).

Currently the application is hardwired to access river watershed data files from a rivers directory on your system. Only the Narragansett Bay or Chesapeake Bay Watershed comes loaded in the rivers directory The rivers directory is only a temporary location as we build our back-end file delivery options. Feel free to grab as many rivers as you want to explore from our Web-based repository. The files include geospatial data for every small branch of every small natural water channel in each watershed (hence their enormity). You may only want to download one watershed to start. The watersheds are available at http://www.oworld.org/mp/code/rivers/. Note that they are not fully implemented in our system yet (and so if you try to load them in other KML-aware applications you will get errors as they link to resources we are not providing at this time).

The application should come up with very little visible outside of our beautiful home planet and some statistics to help us help you understand how it is performing on your system. A screen capture of the May 29th version is provided here:

You can zoom into any place on the planet using your scroll button on your mouse. Alternative methods are explained in the World Wind Walkthrough Tutorial. If you zoom into a geographic area where you have loaded a watershed file, you can click with your right-mouse button and see how the watershed drains from that location on earth (see an example from 41.0 degrees due north of the equator and -77.7 degrees west of Greenwich, England). We are using a good estimated algorithm as we wait for better digital elevation information to be provided with the World Wind back-end services.

Watershed labels are accessible via left mouse button clicks within each loaded watershed boundary (as seen in the example above for the Ohio Watershed).