How to setup WWJ

[Hervé]

Some information for WWJ newbies, gathered here because I thought it would be nice to have everything here:

Introduction

WorldWindJava is a Java API aimed at visualizing 3D globes. It uses language features only found in Java 5.0 and later, but you may want to use Java 6.0, as 5.0 is reaching its end-of-life period, and Java 7.0 is on the way.

WWJ depends on JOGL, a library that exposes the OpenGL API to the Java language. JOGL is one part Java, one part native code, and to work properly it needs the native libraries that make the "glue" between Java and the OpenGL driver for your OS and hardware. The platforms currently supported by JOGL are:

• Windows x86 32bits and 64bits
• Linux x86 32bits and 64bits
• MacOSX
• Solaris x86 32bits and 64bits
• Solaris SPARC 32bits and 64bits

WWJ currently does not use cutting edge OpenGL features, so unless you are using some very old hardware, you should not have compatibility problems. However, one notable feature used is the DXTn compressed texture: although its name comes from the DirectX world, it is an ARB extension, that is available on most graphic cards. As far as I know, this feature is however not available on any 3D accelerator for SPARC workstations. So if you are using a Solaris SPARC box, you are out of luck, sorry.

If your hardware is less than four years old, and is not SPARC based, and if WWJ does not work as it should (ie: crashing, not displaying textures, ...) then chances are that the problem is in your OS and/or drivers, and not in WWJ (well, according to my experience, your mileage may vary).

Note for posters: if you are requesting help from this forum because WWJ doesn't work on your PC, do not forget to describe your hardware, the OS you are using, the Java runtime version you are using (type "java -version" in the command line), and the WWJ version you are using.

Launching examples via the command line

Let's see how you can launch a WWJ example via the command line. All you need is a Java Runtime properly installed, and the WWJ SDK unzipped to the place of your choice. For this example we will use "HelloWorldWind" that you can find in the "gov.nasa.worldwind.examples" package.

On Linux

java -Xmx512m -cp worldwind.jar:gluegen-rt.jar:jogl.jar gov.nasa.worldwind.examples.HelloWorldWind

The -Xmx flag is there to specify that the JVM is allowed to use up to 512Mb of heap. You should not need more than this amount, unless your application is huge, or you have a very nasty memory leak (yes, there are memory leaks in Java).

On Windows

java -Xmx512m -cp worldwind.jar;gluegen-rt.jar;jogl.jar gov.nasa.worldwind.examples.HelloWorldWind

Same as before, only using ";" instead of ":". If there are strange display problems, you may try to add the "-Dsun.java2d.noddraw=true" flag that disables any usage of Direct3D acceleration for Java2D.

Advanced: using another JOGL version
Now let's imagine you have downloaded a newer version of JOGL, and that you want to use it instead of the one provided in the WWJ zip.
Let's say you unzipped the JOGL zip somewhere, and that you created an environment variable called JOGL_HOME that points to the directory that contains the JOGL Jars and native libraries.
Now the command line would be:

java -Xmx512m -cp worldwind.jar:$JOGL_HOME/gluegen-rt.jar:$JOGL_HOME/jogl.jar -Djava.library.path=$JOGL_HOME gov.nasa.worldwind.examples.HelloWorldWind

The "-Djava.library.path" flag tells the JVM where to find native libraries. The syntax after the "=" sign is the same as for LD_LIBRARY_PATH. If the dynamic linker complains it cannot find one of the shared libraries, add the JOGL path to the LD_LIBRARY_PATH too.
Note: this is for Linux, but it is quite similar for Windows, RTFM.

Configuring Eclipse

I am using Eclipse 3.3.2 on Ubuntu using either OpenJDK or SUN's JDK.

General configuration
Go to "Window->Preferences", and in the Preferences window, navigate to "Java->Compiler", and check that the "Compiler compliance level" option is at least "5.0". I am using "6.0".

Creating a WWJ project
If you want to explore WWJ to see how it works, you can create a project with WWJ sources. Clic on "File->New->Java Project", choose "Create project from existing sources" and fill in the path to the WWJ root directory. I prefer to use "Create separate folders for sources and class files" but you can do as you like.

Now click "Next".
Eclipse should be clever enough to find everything. You should however correct a few things in the "Libraries" tab:
First remove the two JARs BasicDemo.jar and worldwind.jar (else classes would be twice in your classpath).
Then expand the jogl.jar entry, click on "Native library location", then on the "Edit..." button, then enter the directory where the native libraries are. In our case, as we are using the JOGL provided with WWJ, it is the root of our project. You can either enter the name of your project or choose by clicking on the "Workspace..." button. It should look like this:

Now click "Finish".
If there is no red marker on your project (and the "Problems" window is empty) then everything compiled without problem. Navigate to the "gov.nasa.worldwind.examples" in the "Package Explorer" window, right click on the "HelloWorldWind.java" file, choose "Run As->Java Application".
And it should work ;-)

Creating a project for your application
If you want to create your own application, based on WWJ, it is a very good idea to create a new project, and to keep the "WWJ" project (that we created just a few lines back) untouched. That way it will be easier to cope with the next WWJ version and its load of surprises.
So click on "File->New->Java Project", fill in your project name, click on "Next", and then in the "Projects" tab, add the "WWJ" project as a dependency. Click on "Finish" and start coding :-)

If there are classpath problems check on the "WWJ" project properties that the JARs are exported for dependent projects: in the "Package Explorer" window, right-click on the "WWJ" project, choose "Properties", navigate to the "Java Build Path" entry, and in the "Order and Export" tab, check that the jogl and gluegen jars are ticked.

Now if you have to make a modification into a WWJ file, copy that file into your project (changing the package is a good idea), and change the configuration file in order to make WWJ use your class. This is sometimes problematic, as this often involves copying a lot of WWJ classes, the WWJ SDK being not as flexible as it pretends to be, but at least when the next WWJ version will come out, your application should still be working with your modifications, and by just modifying your configuration file, you would be able to see how it works with the new WWJ.

Configuring NetBeans

To do... by someone who uses NetBeans ;-)

[nlneilson]

It's good you are posting this, it should be a big help for many.

I downloaded another copy of the source and tried this:

neil@neil:~/WorldWind/WWJ-5$ java -Xmx512m -cp worldwind.jar:gluegen-rt.jar:jogl.jar gov.nasa.worldwind.examples.HelloWorldWind
Exception in thread "AWT-EventQueue-0" java.lang.UnsatisfiedLinkError: no gluegen-rt in java.library.path

There are several things in your post I will try in Eclipse.

Toshiba A105 Notebook, Intel dual core CPU, XP sps3 (WWJ runs fine there) Ubuntu 8.04, 2GB mem, 320GB hdd, Intel 945G video, Eclipse 3.2.2

[Chiss]

I agree this is a nice post for newbies... May I suggest you find/create a place in the WWJ wiki page as well?

http://www.worldwindcentral.com/wiki/Java

Chiss!

[nlneilson]

Got something working in Linux.

[patmurris]

Thanks Hervé, very useful contribution. I made the thread stick, but this should definitely go into the WWC wiki.

[TomServo]

Been working on some WWJava applet tutorials myself:

http://earthissquare.com/2008/08/06/...to-a-web-page/
http://earthissquare.com/2008/08/10/...to-a-location/
http://earthissquare.com/2008/08/13/...bel-thy-earth/

Hi,

The examples on launching WWJ in a web page is great, but, I am unable to successfully do that. I get unsatisfiedlinkerrors..Are there any steps missing? Do we need to sign all the jars? Could you please elaborate further as I am trying to setup a web application with WWJ applet on a html frame.

Thanks, Suma.

[nlneilson]

I have been using Eclipse. Post #1 did not have the configuration for NetBeans so I decided to try in order to help individuals (including myself).

I was able to pull the project from Eclipse and get it to run in NetBeans but this post will concern just the configuration in NetBeans 6.5.

Trying to follow this to set it up there are things that need to be done or clarified.
http://www.worldwindcentral.com/wiki...n_NetBeans_IDE

1. The characters that are not UTF-8 need to be deleted even though they are in the comments, that is straight forward, just click on the errors and it will take you to them.

2. From the above link "In the Swing/AWT Components Palette Manager". In NB 6.5 it is just AWT rather than Swing/AWT or Swing AWT.

3. "Create a helper class ..." That is: File->New File->Java Class
Name the file "WWHelper" and it will add the .java extension. The file contents should look like it does in the link.

4. "Run->Clean and Build Main Project" gives this error:
" ... WorldWindow.java file does not contain class WorldWindow"
That file has

public interface WorldWindow extends AVList

I don't know what the problem is there.

http://forum.worldwindcentral.com/sh...ad.php?t=20768

Originally Posted by kikigey89

first of all, after 3 months of problems with NetBeans IDE I tried Eclipse... and in 5 minutes of using Eclipse everything worked with my annotations

Apparently somebody that knows NetBeans needs to get involved in a current tutorial.

[nlneilson]

http://wiki.netbeans.org/HelloWorldWindJavaSDK
That was written using release 20070817 0 (WWJ 0.4.0 maybe) and NB 5.5

It will work with WWJ 0.5.0 and NB 6.5 for the worldwind.jar but as shown in that link there is no layer panel or status bar.

Someone that has been using NB for WWJ should explain what they have done.

[Chiss]

Originally Posted by nlneilson

Someone that has been using NB for WWJ should explain what they have done.

Hear hear ! I've answered nlneilson call. I've just updated the Wiki page with the following :

This step by step guide was created with NetBeans 6.x and the 0.5.0 release of the SDK. However, the general principals outlined here should work regardless of the SDK version.

Step 1: Unzip the SDK

Step 2: Open NetBeans and create a New Project using the "Java Application" template. Fill in the required details but uncheck the 'Create Main class' box. Your new project should reside in a clean directory.

Step 3: Rename WorldWind's 'build.xml' to something else (ww_build.xml) and copy all the WorldWind's unzipped content to your NetBeans project folder so that the src folders overlap. You should end up with a folder structure very similar to the WorldWind unzipped folder, plus a 'nbproject' and a 'test' folders. The 'build.xml' file is the one created by NetBeans, not the one that came with the zip (which is why we renamed it earlier).

Step 4: From NetBeans, you will notice that some folders/classes are marked with a red exclamation mark. We now need to tell the project about the required libraries. Right-click your project's node and select 'Properties' (typically the last menu item). Select the 'Libraries' node from the Categories tree and press the 'Add JAR/folder' button on the right. Keeping CTRL down, select the 'gluegen-rt.jar' and 'jogl.jar' that are now inside your project folder. Click 'ok'.

Step 5: At this point, only 2 classes in the '...examples.Applet' package don't compile (still have the red exclamation mark). Go back to the 'Libraries' category like before, but this time you need to add the 'plugin.jar' located in your JDK/jre/lib directory (for example, C:\Program Files\Java\jdk1.6.0_10\jre\lib\plugin.ja r)

You can now run any of the examples by right-clicking them and selecting 'Run File' from the contextual menu.

Hope this helps,
Chiss!