Skip navigation links
NASA World Wind

NASA World Wind API

World Wind is a collection of components that interactively display 3D geographic information within Java applications or applets.

See: Description

Packages 
Package Description
gov.nasa.worldwind  
gov.nasa.worldwind.animation  
gov.nasa.worldwind.avlist  
gov.nasa.worldwind.awt  
gov.nasa.worldwind.cache  
gov.nasa.worldwind.data
This package provides classes for converting raw data sources into a form which can be used by standard World Wind components, such as Layer and ElevationModel.
gov.nasa.worldwind.drag  
gov.nasa.worldwind.event  
gov.nasa.worldwind.exception  
gov.nasa.worldwind.geom  
gov.nasa.worldwind.geom.coords  
gov.nasa.worldwind.globes
Provides classes for representing the shape and terrain of a planet.
gov.nasa.worldwind.globes.projections  
gov.nasa.worldwind.layers  
gov.nasa.worldwind.layers.Earth  
gov.nasa.worldwind.layers.mercator  
gov.nasa.worldwind.layers.placename  
gov.nasa.worldwind.layers.rpf  
gov.nasa.worldwind.layers.rpf.wizard  
gov.nasa.worldwind.ogc  
gov.nasa.worldwind.ogc.collada
Provides classes for parsing COLLADA files and streams.
gov.nasa.worldwind.ogc.collada.impl
Provides classes for rendering COLLADA documents.
gov.nasa.worldwind.ogc.collada.io
Provides classes for COLLADA file and stream I/O and relative-path resolution.
gov.nasa.worldwind.ogc.gml  
gov.nasa.worldwind.ogc.kml
Provides classes for parsing KML and KMZ files and streams.
gov.nasa.worldwind.ogc.kml.gx
Provides classes for parsing the Google GX KML extensions.
gov.nasa.worldwind.ogc.kml.impl  
gov.nasa.worldwind.ogc.kml.io
Provides classes for KML and KMZ file and stream I/O and relative-path resolution.
gov.nasa.worldwind.ogc.ows  
gov.nasa.worldwind.ogc.wcs  
gov.nasa.worldwind.ogc.wcs.wcs100  
gov.nasa.worldwind.ogc.wms  
gov.nasa.worldwind.pick  
gov.nasa.worldwind.poi  
gov.nasa.worldwind.render  
gov.nasa.worldwind.render.airspaces  
gov.nasa.worldwind.render.airspaces.editor  
gov.nasa.worldwind.render.markers  
gov.nasa.worldwind.retrieve  
gov.nasa.worldwind.symbology
Provides classes for creating and displaying graphics from standard symbol sets.
gov.nasa.worldwind.symbology.milstd1477  
gov.nasa.worldwind.symbology.milstd2525
Tactical graphics and symbols defined by the MIL-STD-2525 symbology set.
gov.nasa.worldwind.symbology.milstd2525.graphics  
gov.nasa.worldwind.symbology.milstd2525.graphics.areas
MIL-STD-2525 area graphics.
gov.nasa.worldwind.symbology.milstd2525.graphics.lines
MIL-STD-2525 line graphics.
gov.nasa.worldwind.terrain  
gov.nasa.worldwind.tracks  
gov.nasa.worldwind.util  
gov.nasa.worldwind.util.combine  
gov.nasa.worldwind.util.dashboard  
gov.nasa.worldwind.util.gdal  
gov.nasa.worldwind.util.layertree
Displays a list of layers using BasicTree.
gov.nasa.worldwind.util.measure  
gov.nasa.worldwind.util.tree
A tree control drawn in the world window.
gov.nasa.worldwind.util.webview
Provides classes for loading web content, laying out and rendering the content as an OpenGL texture, and interacting with the rendered content.
gov.nasa.worldwind.util.wizard  
gov.nasa.worldwind.util.xml  
gov.nasa.worldwind.util.xml.atom
Provides classes for parsing the Atom namespace.
gov.nasa.worldwind.util.xml.xal
Provides classes for parsing the XAL namespace.
gov.nasa.worldwind.view
The view package contains implementations, and support for implementations of the View interface.
gov.nasa.worldwind.view.firstperson  
gov.nasa.worldwind.view.orbit  
gov.nasa.worldwind.wms  
gov.nasa.worldwindx.applications  
gov.nasa.worldwindx.applications.antenna  
gov.nasa.worldwindx.applications.dataimporter  
gov.nasa.worldwindx.applications.eurogeoss  
gov.nasa.worldwindx.applications.glider  
gov.nasa.worldwindx.applications.sar  
gov.nasa.worldwindx.applications.sar.actions  
gov.nasa.worldwindx.applications.sar.render  
gov.nasa.worldwindx.applications.sar.segmentplane  
gov.nasa.worldwindx.applications.sar.tracks  
gov.nasa.worldwindx.applications.worldwindow  
gov.nasa.worldwindx.applications.worldwindow.core  
gov.nasa.worldwindx.applications.worldwindow.core.layermanager  
gov.nasa.worldwindx.applications.worldwindow.features  
gov.nasa.worldwindx.applications.worldwindow.features.swinglayermanager  
gov.nasa.worldwindx.applications.worldwindow.util  
gov.nasa.worldwindx.applications.worldwindow.util.measuretool  
gov.nasa.worldwindx.examples  
gov.nasa.worldwindx.examples.analytics  
gov.nasa.worldwindx.examples.applet
Examples of a displaying a World Wind globe in a Java Applet.
gov.nasa.worldwindx.examples.dataimport  
gov.nasa.worldwindx.examples.elevations  
gov.nasa.worldwindx.examples.kml
Examples of importing and exporting files in the Keyhole Markup Language (KML).
gov.nasa.worldwindx.examples.layermanager  
gov.nasa.worldwindx.examples.lineofsight
Examples of how to perform line of sight calculations in WorldWind.
gov.nasa.worldwindx.examples.multiwindow
Examples of how to use multiple WorldWind globes in the same application.
gov.nasa.worldwindx.examples.shapebuilder
The shapebuilder package contains shape building applications for 3D shapes, including the rigid shapes (Ellipsoid, Box, Cylinder, Cone, Pyramid, Wedge) and ExtrudedPolygon.
gov.nasa.worldwindx.examples.symbology
Examples of displaying graphics from common symbology sets in World Wind.
gov.nasa.worldwindx.examples.tutorial  
gov.nasa.worldwindx.examples.util  
gov.nasa.worldwindx.examples.util.cachecleaner  
gov.nasa.worldwindx.examples.view  
gov.nasa.worldwindx.performance  

World Wind is a collection of components that interactively display 3D geographic information within Java applications or applets. Applications and applets use World Wind by placing one or more WorldWindow components in their user interface. The World Wind components are extensible. The API is defined primarily by interfaces, so components can be selectively replaced by alternative components.

To use World Wind as an applet, see the package gov.nasa.worldwindx.examples.applet.

WorldWindow is an interface. Toolkit-specific implementations of the interface are provided for Swing/AWT and, in the future, SWT-Eclipse. See WorldWindowGLCanvas.

In addition to WorldWindow, there are five major World Wind interfaces. They are:

In typical usage, applications associate a Globe and several Layers with a Model They then pass that model to a SceneController that displays the globe and its layers in a WorldWindow. The scene controller subsequently manages the display of the globe and its layers in conjunction with an interactive View that defines the user's view of the planet.

The objects implementing the above interfaces may be those provided by World Wind or those created by application developers. Objects implementing a particular interface may be used wherever that interface is called for. World Wind provides several Globe objects representing Earth, Mars and the Earth's moon, and provides basic implementations of Model, SceneController and View.

Most of World Wind's components are defined by interfaces. This allows application developers to create their own implementations and easily integrate them into World Wind.

The WorldWind Class

TODO

Multiple World Wind Windows

TODO

Data Retrieval

World Wind works with enormous quantities of data and information, all of which exist primarily on remote data servers. Retrieval and local caching of that data is therefore a primary feature of World Wind. The classes that implement retrieval are Retriever and RetrievalService.

Retriever encapsulates a single network retrieval request. It is an interface. The most commonly used concrete Retriever is HTTPRetriever, which retrieves data via http. Retrievers are typically created by a Layer to retrieve the data the layer displays, and by an ElevationModel to retrieve elevation data.

RetrievalService manages a thread pool for retrieval tasks. Objects retrieve data by passing the retrieval service a Retriever. The service runs each retriever in an individual thread. Access to the retrieval service is through WorldWind, which holds a singleton instance.

When a retriever's data arrives, the retrieval service calls the retriever's RetrievalPostProcessor, which was specified to the retriever's constructor. The RetrievalPostProcessor is passed the data immediately upon download and determines how to persist it. Persistence and any processing prior to it is object specific. TiledImageLayer, for instance, can convert non-DDS formats to DDS, or simply store the data as-is in the file cache. BasicElevationModel just persists the raw data. The post processor runs in the same thread as the retriever, which is neither the event-dispatching (UI) thread nor the rendering thread, but the one created by the retrieval service for that retriever.

Data that has been previously retrieved or is otherwise local (on disk) is brought into memory in a thread separate from the event-dispatching thread or the rendering thread. One of the World Wind conventions is that no code may access the computer's disk in any way during rendering. Therefore loading the data from disk is dispatched to another thread pool, the ThreadedTaskService. This service has a similar interface to RetrievalService. Tasks it runs typically read the data from disk and add it to the global memory cache (described below).

One consequence of the disk-access restriction is that determining whether needed data is on disk and can be loaded directly, or is not local and therefore must be retrieved, must not be done in the rendering thread. (A disk access is necessary to determine whether the data exists locally.) Objects that load data therefore follow the convention of first checking the memory cache for the desired data, and if it's not there create a Runnable to determine in a separate thread where the data must be drawn from, disk or network. If it's on the disk then the task can simply read it and cache it right away. If it's remote then the task creates a Retriever and requests retrieval. Later, after retrieval has placed the data on disk, the situation will be the local case and data can be loaded into memory within the Runnable.

Memory Cache

So that data can be shared among caching objects, most cached data used within World Wind is cached in a MemoryCache. MemoryCache enable cached data to be shared among all WorldWindWindow instantiations in an application. Thus two Earth globes each displayed in a separate window will share any image or elevation tiles that they are using simultaneously. The same would be true of any place name collections. The constraint this imposes is that cached data that is to be shared must base equals() and hashCode() on fields that are not instance specific to the caching object.

File Cache

All data persisted to or drawn from the local computer is done so by the FileStore No object manages its own storage. The file cache cache manages multiple disk storage locations and unifies access to them. The file cache is a singleton, accessible through the WorldWind singleton.

Picking and Selection

World Wind can determine the displayed objects at a given screen position in a WorldWindow. When the application wants to know what's displayed at a particular point, say the cursor position, it calls a method on WorldWindow that accepts the point and returns a description of what's drawn there. In general the application specifies a pick region rather than a single point, with the region a few pixels wide and high and centered on the point. This provides a pick tolerance and allows the user to indicate something close to but not exactly at the screen position. Since several objects may intersect the pick region, descriptions of all these objects are returned to the application. Which of these objects are meaningful is determined by the application.

World Wind uses a method similar to drawing to detect objects in the pick region. During picking, the frame controller invokes each layer's AbstractLayer.doPick(DrawContext, java.awt.Point). As in drawing, the methods are invoked in turn, according to the layer's position in the model's layer list. During the call, each layer is responsible for determining which of its items, if any, are picked. Prior to traversing the layer list, the frame controller sets the current view's viewport to the pick region specified by the application. When a layer identifies an object that intersects that pick region, it adds a description of that object to the draw context's pick list. Once all layers are traversed, the list of picked items is returned to the application.

It's typically not straightforward for a layer to determine which of its contents intersect a screen-space pick region. To do that usually requires transforming the screen point into model coordinates and determining intersection in that coordinate system. But depth values are ambiguous with only a two-dimensional screen point as input, complicating transformation to model coordinates, and geometric intersection determination can be very difficult and time consuming. To overcome this, World Wind implements a widely used method of sampling the window's color buffer to detect intersection, and makes this method easy for layers to use.

The method works as follows: The frame controller precedes a pick traversal by first setting the current view's viewport to the specified pick region and clearing the color buffer in that region. This clearing occurs in the window's back buffer and is therefore not visible to the user. During traversal, each layer draws itself not in its normal colors but in a set of colors that serve as pick identifiers. Since the result of pick traversal is never displayed, the specific colors used don't matter visually. Each individual pickable item within a layer is drawn with a unique color that makes the item individually identifiable in the color buffer. By reading the region of the color buffer corresponding to the pick region, the specific items intersecting the region can be determined. The layer performs this read and makes this determination after drawing its pickable items.

Since one layer does not know how subsequently traversed layers might overwrite or otherwise affect it once drawn, items it determines have been picked could end up obscured by other layers. The items that intersect the pick region and are visible can be determined only after all layers are drawn. The frame controller therefore reads the final colors from the pick region of the color buffer and passes them to the list of picked items so that those items can compare their pick identifiers with the final colors and mark themselves as "on top." The application then receives the full list of picked items, with the truly visible ones marked as such.

World Wind provides utility classes to make it simple for layers to participate in this picking scheme. See PickSupport

Use of Proxies

A proxy is set by calling Configuration.setValue(java.lang.String, java.lang.Object) for each of the following keys:

After these values are set, all retrievals from the network will go through the specified proxy.

Offline Mode

World Wind's use of the network can be disabled by calling WorldWind.setOfflineMode(boolean). Prior to attempting retrieval of a network resource — anything addressed by a URL — World Wind checks the offline-mode setting and does not attempt retrieval if the value is true.

Path Types

There is only one way to draw a straight line on a plane, but there are several ways to draw a straight line on the surface of a globe. Most shapes support the following path types:

Set the pathType attribute to change how the lines of a shape are drawn (for example, Path.setPathType(java.lang.String)). The LatLon class provides utility methods to calculate points along each type of path.

Skip navigation links
NASA World Wind