This guide walks you through creating a fully functional 3D virtual globe desktop application with NASA WorldWind Java. By the end you will have a running Java Swing application displaying an interactive, OpenGL-rendered Earth with satellite imagery and terrain. All you need is Java 11 or higher and a graphics card with an up-to-date OpenGL 2.0-compatible driver.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/nasaworldwind/worldwindjava/llms.txt
Use this file to discover all available pages before exploring further.
Download the Latest Release
Download the pre-built WorldWind Java release archive from GitHub. It contains all required JARs — including JOGL native binaries — pre-assembled and ready to run.Go to the latest GitHub release and download the
.zip archive for your platform. Extract it to a directory of your choice, referred to below as [WorldWind release].The extracted directory will contain:worldwind.jar— the core WorldWind SDKjogl-all.jarandgluegen-rt.jar— JOGL OpenGL bindingsgluegen-rt-natives-*.jarandjogl-all-natives-*.jar— platform native librariesgdal.jar— GDAL geospatial data format supportrun-demo.bat/run-demo.bash— convenience launcher scripts
Add JARs to Your Classpath
Add the following JARs from the release directory to your project’s classpath (or to your IDE’s library configuration):
JOGL automatically extracts the native binaries from the native JARs at runtime into the user’s temp directory. Keep all JARs in the same directory so JOGL can find them on the classpath.Command-line classpath example (Linux / macOS):
| JAR | Purpose |
|---|---|
worldwind.jar | Core WorldWind SDK — all gov.nasa.worldwind.* classes |
jogl-all.jar | JOGL Java OpenGL bindings (required) |
gluegen-rt.jar | GlueGen runtime (required by JOGL) |
gluegen-rt-natives-<platform>.jar | Platform-specific native OpenGL libraries |
jogl-all-natives-<platform>.jar | Platform-specific JOGL native libraries |
gdal.jar | Optional — needed for GDAL raster/vector data formats |
Compile with classpath
Run with classpath
Create Your First Globe Application
The simplest possible WorldWind application creates a Key points:
WorldWindowGLCanvas, sets a BasicModel on it, and embeds it in a JFrame. The code below is taken directly from SimplestPossibleExample.java in the WorldWind examples:SimplestPossibleExample.java
WorldWindowGLCanvasis the AWT/Swing-compatible OpenGL canvas. It implements theWorldWindowinterface.BasicModelconstructs the default globe (Earth), elevation model, and layer stack as defined inworldwind.xml.- The canvas is added to the
JFrame’s content pane like any other Swing component. - All UI construction must happen on the AWT Event Dispatch Thread — hence the
invokeLatercall.
Run the Application
The release archive includes convenience scripts that set up the classpath and JVM flags automatically.The script compiles and runs the default demo. To run your own class, pass it as an argument:A Swing window will open displaying a 3D globe with satellite imagery. Use the mouse to navigate:
- Windows
- macOS / Linux
run-demo.bat (Windows)
Run a specific class (Windows)
- Left-drag — pan
- Right-drag or scroll wheel — zoom
- Ctrl + drag — tilt and rotate
Building on the Template
For real applications, theApplicationTemplate class in gov.nasa.worldwindx.examples provides a reusable framework with a status bar, layer panel, tool-tip controller, and highlight controller already wired up. Extend AppFrame and call the static start method:
ApplicationTemplate pattern
AppFrame and override initialize or createAppPanel, then call ApplicationTemplate.start:
MyWorldWindApp.java
Adding Your First Layer
Layers are the primary mechanism for adding content to the globe.RenderableLayer accepts any Renderable — including PointPlacemark, shapes, and annotations. The following example adds a named placemark at a geographic coordinate:
AddingALayer.java
Position.fromDegrees(lat, lon, elevation)— constructs a geographic position.WorldWind.CLAMP_TO_GROUND— pins the placemark to the terrain surface regardless of elevation value.ApplicationTemplate.insertBeforeCompass(wwd, layer)— inserts your layer at the correct z-order position, beneath the compass HUD layer.wwd.getModel().getLayers()— returns theLayerListdirectly if you prefer to manage layer order yourself.
Troubleshooting
The globe window opens but the globe is black or blank
The globe window opens but the globe is black or blank
This is almost always caused by an out-of-date graphics driver. WorldWind requires OpenGL 2.0 or higher.
- Windows: Visit your GPU manufacturer’s site — NVIDIA, AMD, or Intel — and install the latest driver. For laptops, check the laptop OEM’s support page.
- macOS: Ensure macOS is up to date. Apple ships OpenGL drivers as part of the OS.
- Linux: Update Mesa (
sudo apt update && sudo apt install mesa-utils) or install the proprietary driver for your GPU.
UnsatisfiedLinkError or missing JOGL native libraries
UnsatisfiedLinkError or missing JOGL native libraries
JOGL performs runtime extraction of native binaries from the native JAR files (e.g.,
jogl-all-natives-windows-amd64.jar) into the user’s temp directory. This requires that:- The native JAR files are on the classpath (in the same directory as
jogl-all.jar). - The user’s temp directory is writable by the JVM process.
- Extract the contents of
gluegen-rt-natives-<platform>.jarandjogl-all-natives-<platform>.jar. - Place the extracted
.dll/.so/.dylibfiles in the working directory or a directory onjava.library.path. - Remove the native JAR files from the classpath.
- Add the JVM flag:
-Djogamp.gluegen.UseTempJarCache=false
ClassNotFoundException for gov.nasa.worldwind.*
ClassNotFoundException for gov.nasa.worldwind.*
Verify that
worldwind.jar is on the runtime classpath. When running from the command line, double-check that:- You are
cd-ed into the WorldWind release directory, or that the full path toworldwind.jaris specified. - Both compile-time (
javac -cp ...) and run-time (java -cp ...) classpath arguments includeworldwind.jar. - In IDEs (IntelliJ IDEA, Eclipse, NetBeans), confirm the JAR is listed under the project’s library dependencies.
Application crashes with WWAbsentRequirementException
Application crashes with WWAbsentRequirementException
WWAbsentRequirementException is thrown when WorldWind detects at render time that the system does not meet minimum graphics requirements. The ApplicationTemplate.AppFrame already handles this:Rendering exception handler (from ApplicationTemplate.java)