COMP 310
NASA WorldWind Java SDK
COMP 310 |
NASA WorldWind Java SDK |
|
|
WorldWind Java (WWJ) is an free, open-source Geographic Information System (GIS) from NASA that provides high-resolution imagery of the world and a framework for displaying that information including capabilities for displaying additional, overlayed information.
WWJ is not a stand-alone application but rather, a software development kit (SDK) that can be used to build custom applications.
Normally, the course staff will supply a ready-to-use WWJ distribution through a read-only SVN repository that you can include in your codebase by using the svn:externals property. Follow the directions for adding Libraries in Java to make the WWJ code available to your application.
Mouse with scroll wheel:
Single button mouse:
The course staff may supply a read-only SVN repository location for a map
package provides some basic WWJ map capabilities such as
Position class that can have
an altitude (hieght in the sky) different than its elevation (height of the
ground at that point). The purpose of this package is to help students get started with WWJ and provide some simple utilities for quickly getting a map to display in their applications. It is NOT intended as a definitive implementation of WWJ usage but rather as a quick and easy starting point for novices. Students are free to copy the provided code and modify it to suit their specific needs.
See the
documentation for the map package.
Important usage note: While the map package
does provide some customized WWJ components that are Serializable,
it is NOT recommended that any WWJ-related entities ever be
serialized and transmitted over a network due to the fact that most
underlying WWJ classes are not serializable and in some cases,
platform-dependent. Instead, always send
factories for the desired WWJ components and
construct those components directly on the target machine.
Typically, the course will provide a local repository link for the WWJ libraries in use for that year. The following information is just for those who wish to set up WWJ outside of the course.
The full source code and un-released versions can be obtained from the WWJ GitHub home (see link above)
The critical JAR files in a distribution are:
The library folder must also contain all *.dll, *.jnilib, and *.so files that came with the above JAR files.
The WWJ distribution comes set up for 32-bit operation. The DLL's for 64-bit operation are inside these two JAR files:
A JAR file is just a specialized ZIP file, so most ZIP archive programs, such as WinRAR, can open them. You can also use Java's built-in "jar" utility to extract the files: jar xf filename.jar
All these files are generally in the root of the downloaded ZIP file from NASA.
Building the source code (Only necessary in VERY specialized and unique situations!)
The source code comes with an ANT build script (build.xml). Eclipse has ANT script capability built-in:
These problems seem to have gone away in the latest WWJ 2.0+ versions, so look elsewhere for problems before attempting these drastic solutions.
The Java Open GL (JOGL) libraries appear to have been broken by Oracle's release of Java JDK 1.7.06 (or so) on the 10.8 version of Mac OS.
Typical error is a class not found error on: apple.awt.ComponentModel
A switch to the newer JOGL 2 is rumored to fix the problem (Note that WWJ 2.0 uses JOGL 2):
One probably needs to get the very latest version of JOGL as implied by this post:
JOGL is available from http://jogamp.com
To build WWJ, you need ANT: http://ant.apache.org/ (already included in Eclipse).
There is a new v1.5 build avaiable from WWJ in their SVN repository, but does not seem to be released yet. It does not seem to be using JOGL 2. The ver 2.0 of WWJ certainly does.
WWJ docs say that one should always make changes to WWJ components in the Java GUI event dispatch thread:
Be sure to make changes to World Wind on the event dispatch thread (EDT). That’s the drawing thread. If changes are made to shapes, layers, views, etc. on a separate thread, they could occur while the model is being drawn and the drawing thread could encounter inconsistent or incoherent state. (ref)
The Java documentation says that all, save a few, operations on Swing components must take place on the GUI event dispatch thread, including GUI instantiation:
Swing event handling code runs on a special thread known as the event dispatch thread. Most code that invokes Swing methods also runs on this thread. This is necessary because most Swing object methods are not "thread safe": invoking them from multiple threads risks thread interference or memory consistency errors. Some Swing component methods are labelled "thread safe" in the API specification; these can be safely invoked from any thread. All other Swing component methods must be invoked from the event dispatch thread. Programs that ignore this rule may function correctly most of the time, but are subject to unpredictable errors that are difficult to reproduce. (ref)
In general Swing is not thread safe. All Swing components and related classes,
unless otherwise documented, must be accessed on the event dispatching thread...thus care must be taken to transfer control to the event dispatching thread
when constructing and showing an application or applet. The preferred way to
transfer control and begin working with Swing is to use invokeLater.
(ref)
One consequence of Swing being single-threaded is that you must create a Swing application's UI on the EDT only. It is incorrect to create this UI on any other thread, such as the main thread that runs a Java application... (ref)
Typically, in compliance with the above stated requirements, we create the entire MVC, including the view with its Swing components, on the event dispatch thread as such:
SwingUtilities.invokeLater(new Runnable() {
public void run() {
Controller c = new Controller();
c.start();
}
}
This is the default startup code style that WindowBuilder uses when auto-generating a main method.
The following problems seem to have gone away in the latest WWJ 2.0+ versions, so look elsewhere for problems before doing the following as this will cause problems with running your code on other people's machines.
(11/20/2012) With WWJ 2.0 on Windows, we had seen cases where starting the WWJ display on the GUI event thread will cause the system to lock up with a blank white view. There appears to be a bug in WWJ 2.0 where the process to read data from the NASA servers is started on the current thread (the event dispatch thread, above) instead of a new thread. This problem does not seem to show up on Macs, though the Windows behavior is arguably correct, given the statements above regarding Swing operations and the event dispatch thread. Note this problem seems to be solved on the latest WWJ version.
The solution is to not create the GUI on the event thread:
final Controller c = new Controller();
SwingUtilities.invokeLater(new Runnable() {
public void run() {
c.start();
}
}
At this point, it is not clear how this will affect dynamically generated WWJ displays. One should always be very aware of which thread WWJ and Java GUI calls are made from.
On some machines which have very high resolution displays, the operating system may "magnify" the size of icons, text and other UI components in order to make them more readable. Otherwise, on these types of displays, particularly on the physically smaller laptop screens, the normal text and things like text fields can be so exceedingly small as to be unusable. This issue only shows up on "high DPI" screens, typically greater than 1080p HD resolution, so it may not show up when a high resolution laptop is connected to a lower resolution monitor.
While native Java code can typically handle these operating system-driven magnifcations and display the Swing GUI elements in a reasonable size, since WWJ's map is displayed using the Java OpenGL native code library, the map display may not properly register the scaling needed to accommodate the operating system magnification.
The symptom is that the map does not properly fill the parent Java Container in which it is placed. For instance, the map may only occupy exactly one half the width and one half the height of the enclosing container when the system magnification is set to 200%.
This problem has been explicitly identified on Windows machines. It is not clear at this point how prevalent it is in Mac and Linux machines.
This work-around allows the operating system to control the scaling of the WWJ map since the native JOGL code is unable to do so itself.
Reference:
© 2017 by Stephen Wong