Skip to main content

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.

NASA WorldWind Java ships with built-in parsers and writers for a broad range of geospatial file formats under the gov.nasa.worldwind.formats package hierarchy. Each sub-package targets a specific format family, from vector data (Shapefile, GeoJSON, VPF) to raster imagery (GeoTIFF, DDS, RPF) and GPS tracks (GPX, NMEA). When the optional native GDAL library is present, dozens of additional formats become available through GDALDataRasterReader.

Format Overview

PackageFormatKey Classes
formats/shapefileESRI ShapefileShapefile, ShapefileRecord, ShapefileLayerFactory
formats/geojsonGeoJSONGeoJSONDoc, GeoJSONGeometry, GeoJSONObject
formats/tiffGeoTIFF rasterGeotiffReader, GeotiffWriter, GeoTiff
formats/dtedDTED elevationDTEDRasterReader (in data package)
formats/gpxGPX GPS tracksGpxReader, GpxTrack, GpxTrackPoint
formats/nmeaNMEA-0183 sentencesNmeaReader, NmeaTrackPoint
formats/rpfCADRG/CIB raster mapsRPFFrameFilename, RPFTOCFile, RPFRasterReader
formats/vpfVector Product FormatVPFDatabase, VPFCoverage, VPFFeatureClass
formats/ddsDirectDraw SurfaceDDSCompressor, DDSDecompressor
formats/csvCSV tabular dataCSVReader
formats/georssGeoRSS feedsGeoRSSParser
formats/worldfileWorld file raster georefWorldFile
formats/nitfsNITF imageNITFSImageBand, NITFSSegment
With the native GDAL library present and configured (AVKey.GDAL_PATH), GDALDataRasterReader additionally supports ECW, MrSID, JP2000, HDF, NetCDF, VRT, and any other GDAL-registered driver. See Data Raster API for GDAL details.

Shapefile (formats/shapefile)

The Shapefile package provides full support for reading ESRI Shapefile (.shp/.dbf/.shx/.prj) vector datasets.

Classes

ClassDescription
ShapefileTop-level reader; iterates ShapefileRecord objects from a .shp file.
ShapefileRecordBase class for all record types; carries geometry and attribute reference.
ShapefileRecordPointA single (x, y) point record.
ShapefileRecordPolylineOne or more polyline parts, each a sequence of points.
ShapefileRecordPolygonOne or more polygon rings with optional holes.
ShapefileRecordMultiPointMultiple points in a single record.
ShapefileRecordNullEmpty / null geometry record.
DBaseFileOpens the .dbf attribute table.
DBaseRecordA single row from the .dbf attribute table.
DBaseFieldColumn metadata (name, type, length).
ShapefileLayerFactoryHigh-level factory: creates a RenderableLayer or Layer from a Shapefile URL.
ShapefilePolygonsOptimised rendering of polygon Shapefiles as a single Renderable.
ShapefilePolylinesOptimised rendering of polyline Shapefiles.
ShapefileExtrudedPolygonsExtrudes polygon footprints to 3D buildings using a height attribute.
ShapefileRenderableBase class for the optimised Shapefile renderables.
ShapefileUtilsUtility methods (e.g., intersect sector, coordinate conversion).

Reading a Shapefile

Opening a Shapefile and reading records
Shapefile sf = new Shapefile(new File("roads.shp"));

// Iterate all records
while (sf.hasNext()) {
    ShapefileRecord record = sf.nextRecord();

    if (record instanceof ShapefileRecordPolyline) {
        ShapefileRecordPolyline line = (ShapefileRecordPolyline) record;
        int parts  = line.getNumberOfParts();
        int points = line.getNumberOfPoints();

        // Geometry — positions in all parts as a flat VecBufferSequence
        VecBufferSequence geom = line.getCompoundPointBuffer();
    }

    // Attribute data via DBaseRecord
    DBaseRecord attrs = record.getAttributes();
    if (attrs != null) {
        Object nameVal = attrs.getValue("NAME");    // column name
        System.out.println("NAME = " + nameVal);
    }
}
sf.close();

Factory-based Layer Creation

ShapefileLayerFactory — create a layer from URL
ShapefileLayerFactory factory = new ShapefileLayerFactory();

// Asynchronous load; callback receives the created Layer
factory.createFromShapefileSource("file:///data/admin_boundaries.shp",
    new ShapefileLayerFactory.CompletionCallback() {
        @Override
        public void completion(Object result) {
            Layer layer = (Layer) result;
            SwingUtilities.invokeLater(() ->
                wwd.getModel().getLayers().add(layer));
        }
        @Override
        public void exception(Exception e) {
            e.printStackTrace();
        }
    });

GeoJSON (formats/geojson)

The GeoJSON package parses RFC 7946-compliant GeoJSON documents.
GeoJSON — reading a document
GeoJSONDoc doc = new GeoJSONDoc(new File("features.geojson"));
doc.parse();

for (GeoJSONObject obj : doc.getObjects()) {
    if (obj instanceof GeoJSONFeatureCollection) {
        GeoJSONFeatureCollection fc = (GeoJSONFeatureCollection) obj;
        for (GeoJSONFeature feature : fc.getFeatures()) {
            GeoJSONGeometry geom = feature.getGeometry();
            // geom may be GeoJSONPoint, GeoJSONLineString,
            // GeoJSONPolygon, GeoJSONMultiPolygon, etc.
        }
    }
}

GeoTIFF (formats/tiff)

The tiff sub-package provides a pure-Java GeoTIFF implementation independent of GDAL.
ClassDescription
GeotiffReaderReads GeoTIFF files into DataRaster (implements Disposable).
GeotiffWriterWrites BufferedImage or elevation data as a GeoTIFF with georeferencing.
GeoTiffConstants and helper methods for the GeoTIFF specification.
GeotiffMetaDataCarries parsed georeferencing metadata (projection, tie-points, pixel scale).
TIFFReaderLow-level TIFF baseline parser.
GeotiffReader — reading imagery
GeotiffReader reader = new GeotiffReader(new File("imagery.tif"));
try {
    // Read the primary image as a BufferedImage
    BufferedImage image = reader.read(0); // band index 0
    // Georeferencing
    double[] tiePoints  = reader.getMetadata().getTiePoints();
    double[] pixelScale = reader.getMetadata().getPixelScale();
} finally {
    reader.close();
}
GeotiffWriter — writing a georeferenced image
GeotiffWriter writer = new GeotiffWriter(new File("output.tif"));
writer.write(sector,     // geographic extent
    bufferedImage);      // image data
writer.close();

GPX (formats/gpx)

Reads GPS Exchange Format files (.gpx) for tracks, routes, and waypoints.
GPX — loading tracks
GpxReader gpx = new GpxReader();
gpx.readFile("tracks/flight.gpx");

for (Track track : gpx.getTracks()) {
    for (TrackSegment seg : track.getSegments()) {
        for (TrackPoint pt : seg.getPoints()) {
            double lat  = pt.getLatitude();
            double lon  = pt.getLongitude();
            double ele  = pt.getElevation(); // metres
        }
    }
}

NMEA (formats/nmea)

Parses NMEA-0183 GPS sentences (e.g., from a serial GPS receiver or log file).
NMEA — reading track points from a file
NmeaReader nmeaReader = new NmeaReader();
nmeaReader.readFile("gps.log");

for (TrackPoint pt : nmeaReader.getPoints()) {
    double lat = pt.getLatitude();
    double lon = pt.getLongitude();
    double ele = pt.getElevation();
}

RPF — Raster Product Format (formats/rpf)

RPF (MIL-STD-2411) encompasses CADRG topographic maps and CIB (Controlled Image Base) imagery used by military applications. Key classes:
  • RPFTOCFile — reads the A.TOC table-of-contents index file.
  • RPFFrameFilename — decodes an RPF frame file name.
  • RPFRasterReader — implements DataRasterReader for individual frame files.
  • RPFGenerator — generates a DataRaster mosaic from a set of RPF frames.

VPF — Vector Product Format (formats/vpf)

VPF (MIL-STD-600006) is the military standard for vector topographic data. Key classes:
  • VPFDatabase — opens a VPF database directory.
  • VPFLibrary — a collection of coverages within a database.
  • VPFCoverage — a thematic data layer (e.g., roads, hydrography).
  • VPFFeatureClass — features within a coverage.

DDS (formats/dds)

DirectDraw Surface (.dds) is the preferred texture format for WorldWind’s tile cache because GPU-decompression (DXT1/DXT3/DXT5) reduces VRAM bandwidth.
DDSCompressor — compressing an image file
// Compress an image file directly to a DDS ByteBuffer
ByteBuffer ddsData = DDSCompressor.compressImageFile(
    new File("tile.png"),
    new DXTCompressionAttributes());

// Write to file
WWIO.saveBuffer(ddsData, new File("tile.dds"));

World File (formats/worldfile)

A world file (.jgw, .pgw, .tfw, etc.) georef-encodes a paired raster image file with a six-parameter affine transformation.
WorldFile — reading affine georeferencing
File wf = new File("aerial.jgw");
double[] params = WorldFile.decodeWorldFile(wf);
// params[0] = pixel width, params[1] = row rotation,
// params[2] = col rotation, params[3] = pixel height (negative),
// params[4] = X of upper-left pixel centre,
// params[5] = Y of upper-left pixel centre

Build docs developers (and LLMs) love