Hands-On Introduction and Tutorial for Setting up and Running NASA's First-Class Java WorldWind Earth Model Simulation

What Is It?

What is WorldWind? Well let me quote NASA’s site directly:

WorldWind is an open source virtual globe API. WorldWind allows developers to quickly and easily create interactive visualizations of 3D globe, map and geographical information. Organizations around the world use WorldWind to monitor weather patterns, visualize cities and terrain, track vehicle movement, analyze geospatial data and educate humanity about the Earth.

There are three “flavors”:

1) Web WorldWind – to build Web applications in your browser.

2) WorldWind Android – to build Android applications.

3) WorldWind Java – to build standalone Java applications for Linux or Windows.

This article covers the application of WorldWind Java – but the classes are pretty much the same across all three application types. The specific site for the Java application side is here –https://worldwind.arc.nasa.gov/java/

Note that for this article I used an older version of WorldWind and a limited set of terrain files. So if you use the latest / greatest version of WorldWind along with a full set of terrain files, the model will look much better than what is seen in these videos.

Why I think it’s Very Cool

From my perspective it’s a high fidelity Earth model that has a tremendous amount of unique and exciting capabilities and features (trust me – this article doesn’t even scratch the surface – no pun intended – of what this system is capable of doing). The developer is only limited by his or her imagination.

Introduction Video

I would suggest that you watch the two short videos below (I recorded all the videos on my home Tower) – as they will give you a quick idea of the utility of using NASA’s WorldWind Earth modeling and simulation tool. Note that the video capture was performed at 10 frames-per-second so these two videos are not as smooth as they would be if I used a graphics video capture card. Click on the lower right square icon (next to the sound / speaker icon) to enlarge the video to almost the size of the monitor in order to more easily view it.

This first video is a general overview.

This second video focuses more on the aspects of watching a simulation unfold and changing observer perspectives by hand (manipulating the Earth model with the mouse).

If you’re intrigued as a software developer, then continue on with the article and I’ll explain this particular code architecture and how to set up the system (it’s really not complicated). Throughout the article are several more videos, each of which is an informal code walk-through for a specific class. And understand that there are many different ways to set up applications with WorldWind – this is just a simple, straight-forward approach for demonstration purposes.

At the end of the article are all of the files needed to run the project without making any code modifications – simply install the required software tools (Java JDK, NetBeans IDE) and the project and support files, and … run the project. There is also as section that explains how to download the pertinent files to just run the code as an executable (jar file) with supporting files (DLLs, library jar files, and terrain files).

High-Level Architecture and Software Layout

System Discussion

At a high level think of it like a physical game with game board and pieces. The Earth model is the game board and the model objects are equivalent to the game pieces that you place on the board. So when you first start out, you have to remove the game board from the box and lay it on the table – in the same way you launch the Earth model and prepare it for the model objects. Then you select the game pieces on the board – in the same way you build / select model objects and put them into the Earth model. That’s it. As a side note, no explicit design pattern was used for this project.

Thus there are two main elements to consider: 1) the Earth model and simulation engine, and 2) the user-designed objects that will be used as part of the Earth model and simulation. In this case, the model objects are trajectory objects (that traverse across the globe) and radar objects (stationary on the globe and track the trajectory objects).

The classes in this project are organized as follows:

Driver Class
This class sets the user preferences, builds the trajectory objects and radar objects, loads the preferences and objects into a data object, builds the Earth model (and passes the data object to it via the constructor) and launches the simulation.

Earth Model
This class sets up the Earth model, configures the selected layers, and drives the simulation.

Model Objects
There are two classes of models: 1) the TrajectoryObjects class, and 2) the RadarObjects class. The TrajectoryObjects class contains the properties and propagation algorithms for objects that move at or above the surface of the Earth model. The RadarObjects class contains the properties for stationary objects on the surface of the Earth model that track the moving objects.

Code Diagram

The block diagram is shown below. The driver class EarthProj does the following:

1) builds the trajectory and radar objects and sets their user-specified properties,

2) builds the ScenarioSettings object (this is the data object) and sets the user-specified parameters as well as loads the trajectory and radar object arrays,

3) builds the EarthView object, and

4) launches the demonstration simulation (via an EarthView class method).

Class Description

The following is a set of more detailed descriptions for each class.

Video Walk-Through of the Main

The following video is high-level and is a walk-through of driver class EarthProj and one of the methods of class EarthView. Basically it explains the user settings and the start-to-finish process for setting up and running a simulation.

Code Discussion

Class TrajectoryObjects

The following is an informal code walk-through of the TrajectoryObjects class. Click on the lower right square icon (next to the sound / speaker icon) to enlarge the video to almost the size of the monitor in order to more easily view it.


Class RadarObjects

The following is an informal code walk-through of the RadarObjects class. Click on the lower right square icon (next to the sound / speaker icon) to enlarge the video to almost the size of the monitor in order to more easily view it.


Class ScenarioSettings

The following is an informal code walk-through of the ScenarioSettings class. Click on the lower right square icon (next to the sound / speaker icon) to enlarge the video to almost the size of the monitor in order to more easily view it.


Class EarthView

The following is an informal code walk-through of the EarthView class. Click on the lower right square icon (next to the sound / speaker icon) to enlarge the video to almost the size of the monitor in order to more easily view it.

This next video is a demonstration of the JDesktop – which acts as a desktop upon which other JPanels can be mounted and moved around. This allows the developer to build a Swing setup that has flexibility in that the panels can be moved around during run-time.

Class BuildJPanel

The following is an informal code walk-through of the BuildJPanel class. Click on the lower right square icon (next to the sound / speaker icon) to enlarge the video to almost the size of the monitor in order to more easily view it.

Class CustomOrbitView – Resolving the Clipping Distance Issue

Depending on the observer’s location and the default clip distance settings, at times the view of the far side of a trajectory may be cut off as shown below.

Thus it’s important to give the user the ability to set the near and far clipping distance values. As shown below, the clipping effect can be eliminated.

The following is an informal code walk-through of the CustomOrbitView class. Click on the lower right square icon (next to the sound / speaker icon) to enlarge the video to almost the size of the monitor in order to more easily view it.

Run the Software “Out of the Package”

Instructions for Running the Project Executable (Fastest Setup Time)

If you would like to just run the executable on your desktop – without using the NetBeans IDE – to see the demo simulation, then you’ll need to download the earthdata.zip and simproject.zip files from the links below to your desktop. The assumption is that you’re running a Windows 64-bit operating system.

Once both files are on your desktop, do the following:

1) Unzip the simproject.zip file and then navigate down into the Earth_Proj directory as shown below:

Copy (or move) the Run_Time directory to your desktop and then go into it and it should look like this:

2) Unzip the earthdata.zip file on your desktop (it is over 700 MB in size so it will take 5-10 minutes depending on the speed of your computer) – then go into it and find the WorldWindData directory as show below.

Move the (cut and paste) the WorldWindData directory into the Run_Time directory on your desktop.

3) In the Run_Time directory, double-click on the EarhProj.jar file – as shown below – and the simulation will begin. If you have any problems, feel free to email me at my contact email address at the end of the article.

Instructions for Running Project in NetBeans (Slower Setup Time)

If you would like to run this project software “out of the box” but from the NetBeans IDE (in the event that you will want to start making your own code updates) then then you’ll need to download the earthdata.zip and simproject.zip files from the links below.

Keep in mind that that for this effort, I used NetBeans 8.1, which is a bit old. I have three versions of NetBeans on my Tower – the NetBeans Community’s NetBeans 8.1 and NetBeans 8.2, and the Apache NetBeans Community’s NetBeans 9.0. In this particular case, I meant to use 8.2 but started using 8.1 by accident – it doesn’t matter as the project will work fine in all three IDEs.

Once both files are on your desktop, do the following:

1) 1) Unzip the simproject.zip file and then navigate down to find the Earth_Proj directory as shown below:

Move the EarthProj_Tower directory to your desktop.

2) Unzip the earthdata.zip file on your desktop (it is over 700 MB in size so it will take 5-10 minutes depending on the speed of your computer) – then go into it and find the WorldWindData directory as show below.

Move the (cut and paste) the WorldWindData directory into the EarthProj_Tower directory on your desktop – the directory should look like this when you’re done:


3) If you don’t have the Java Development Kit 8 (JDK-1.8+) installed on your computer, then download it from the Oracle site and install it – the instructions follow below in the Software Tools Requirements section. If it is already installed then skip to the next step.

4) If you don’t have NetBeans IDE 8.1 installed on your computer, then download it from the NetBeans.org site and install it – the instructions follow below in the Software Tools Requirements section. If it is already installed then skip to the next step.

5) Start NetBeans 8.1 and navigate to open the “EarthProj_Tower” project on your desktop – allow the IDE to scan the project files and then click the green triangle (as shown below) and the simulation will begin.

If you want to use a more recent NetBeans IDE, then Apache NetBeans 9.0 will work fine – it is shown below, ready to run.

Source Code Documentation – Javadoc

The formal documentation for the project is contained in the codejavadoc.zip file below. To access the documentation, simply download this file (click on the link), and then unzip it – it will create a “javadoc” directory two levels down. Go into the javadoc directory and click on index.html or drag the index.html file into your preferred browser. If you click on the index.html file, it may open in Internet Explorer and it doesn’t work well in that browser – so if that’s the case then just drag the index.html file to your favorite browser (Brave, Firefox, Chrome, etc.) – either into the main window or into the URL address bar.

The following is an example of what you should see.

Software Tools Requirements

Software Tools

This project was put together with: 1) Java Development Kit (JDK) 1.8, and 2) NetBeans 8.1 IDE, running on a Windows 8.1 Operating System (OS). Keep in mind that this code (the Java source code, the WorldWind and JOG jar files and DLL files) could easily be assembled quickly into an IDE such as Intellij IDEA or Eclipse. This could also easily be run in Linux – the main differences are that in Windows, Dynamic Link Libraries – called DLLs, are used, whereas in Linux the equivalent would be Shared Objects – called SOs. Thus you’d need to get the JOG .SO files for Linux (I actually have them if you need them – just email me).

Java Development Kit – JDK 8

You can obtain the JDK 8 from Oracle’s site at https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html. Note that if you don’t have an account with Oracle then you’ll have to set one up before being able to download the JDK – it doesn’t cost anything (there’s no license fee) but you need to be registered (or you can’t download the installation package).

Assuming you’re running a Windows 64-bit operating system, you’ll want to download the package that’s highlighted in yellow as shown below.

NetBeans Integrated Development Environment (IDE) 8.1

The download link for NetBeans 8.1 is https://netbeans.org/downloads/8.1. I would suggest that you download the largest and most feature-filled package (circled below on the right). Note that if you don’t have a JDK installed, NetBeans will not continue its installation – so make sure that you install the JDK first.

Wrap Up

NASA WorldWind Code Base and Earth Model Data Files

Here are some useful WorldWind sites.

The direct link to NASA’s WorldWind site is https://worldwind.arc.nasa.gov/
The code base (Github repository) is here – https://github.com/NASAWorldWind/WorldWindJava.
The latest release can be obtained from here: https://github.com/NASAWorldWind/WorldWindJava/releases/tag/v2.1.0

Comments or Questions

If you have comments – then please make them here at the end of the blog article. If you have questions that you want to address to me directly, then feel free to email me at mikescodeprojects@protonmail.com.

Published by Joys and Sorrows of Coding

Originally my degree was in Aerospace Engineering but I started coding in school and was hooked. In those days it was FORTRAN and reverse Polish notation on my hand-held HP 41-CV computer. Later I learned C, Pascal, Matlab, Java, C++, HTML and Python. Now I'm learning Android (Java) with Android Studio. The main IDEs that I use are NetBeans, IntelliJ IDEA, and Android Studio.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: