Raster Data Processing

This page documents the raster data processing subsystem in GeoTools, focusing on how the library reads, transforms, manipulates, and renders gridded geospatial data such as satellite imagery, aerial photographs, digital elevation models, and other forms of raster data. For vector data processing, see Vector Data Processing.

Overview

GeoTools provides comprehensive support for working with raster data through a collection of components that handle loading, processing, and rendering operations. The raster data processing subsystem incorporates several key concepts:

• GridCoverage - The fundamental data model representing raster data with geospatial reference
• Image processing operations - Transformations, filtering, and other operations on raster data
• Mosaicking - Combining multiple images into a seamless coverage
• Reprojection - Converting between coordinate reference systems
• Rendering - Visualizing raster data with appropriate styling

100%

Core Components

GridCoverage2D

GridCoverage2D is the central data model for raster data in GeoTools. It extends the OGC GridCoverage interface and associates a RenderedImage with its geospatial position through:

• A coordinate reference system (CRS)
• A transformation from grid coordinates to world coordinates
• Optional metadata

This model allows raster data to be properly positioned in geographic space, enabling operations like reprojection and integration with vector data.

ImageWorker

The ImageWorker class provides a fluent API for applying operations on raster data. Built on Java Advanced Imaging (JAI), it simplifies complex image processing tasks through a chain of operations:

100%

Key operations provided by ImageWorker include:

Operation Type	Examples	Purpose
Geometric	scale(), crop(), affine(), warp()	Change size and shape
Color	bandSelect(), forceColorSpaceRGB(), forceGrayscale()	Manipulate color spaces
Format	format(), rescale(), binarize()	Change data representation
Statistical	histogram(), getMinimums(), getMaximums()	Compute image statistics
Output	write(), writePNG(), writeGeoTIFF()	Save to different formats

GridCoverageReaders

GridCoverage readers are responsible for loading raster data from various sources into the GridCoverage2D model. The architecture follows a plugin pattern with format-specific implementations:

100%

The readers handle tasks such as:

• Reading metadata from the source file
• Establishing the coordinate reference system
• Creating the grid-to-world transformation
• Supporting overviews for efficient rendering at different scales
• Handling multi-dimensional data (time, elevation, etc.)

Image Processing Operations

GeoTools provides extensive image processing capabilities through the ImageWorker class, which acts as a wrapper around JAI operations while adding geospatial awareness.

Common Operations

Geometric Operations

// Scale an image to 50% of its original size
ImageWorker worker = new ImageWorker(sourceImage);
worker.scale(0.5, 0.5, 0, 0);
RenderedImage result = worker.getRenderedImage();

Color Transformations

// Convert a RGB image to grayscale
ImageWorker worker = new ImageWorker(sourceImage);
worker.forceColorSpaceGRAYScale();
RenderedImage result = worker.getRenderedImage();

NoData Handling

NoData values represent pixels with no valid data. GeoTools provides mechanisms to define and handle these values:

// Set NoData value and create a ROI from it
ImageWorker worker = new ImageWorker(sourceImage);
worker.setNoData(RangeFactory.create(-9999, -9999));
worker.setROI(worker.getImageAsROI());

Image Reprojection

Reprojection transforms raster data from one coordinate reference system to another:

100%

The reprojection process involves:

1. Determining the mathematical transformation between source and target CRS
2. Creating a warping operation that applies this transformation
3. Resampling the image using an appropriate interpolation method
4. Handling edge cases like anti-meridian crossing

Image Mosaic System

The Image Mosaic system is one of the most powerful features of GeoTools' raster processing capabilities, allowing multiple individual images to be combined into a single seamless coverage.

Mosaic Architecture

100%

The key components are:

1. ImageMosaicReader - Entry point that loads and manages the mosaic
2. RasterManager - Handles requests for a specific coverage within the mosaic
3. GranuleCatalog - Indexes and provides access to granules (individual images)
4. GranuleDescriptor - Represents a single granule with methods to load it

Granule Catalogs

The GranuleCatalog is responsible for indexing and providing efficient access to granules. Different implementations exist:

Catalog Type	Implementation	Best For
JDBC-based	GTDataStoreGranuleCatalog	Large datasets with database backend
In-memory	STRTreeGranuleCatalog	Small to medium datasets
Caching	CachingDataStoreGranuleCatalog	Improved performance with caching

Catalogs support querying by:

• Spatial extent (bounding box)
• Time dimension
• Elevation dimension
• Custom dimensions

Mosaic Processing Pipeline

When a request is made to an ImageMosaicReader, the following processing pipeline is executed:

100%

Important aspects of this pipeline include:

1. Granule Selection - Only granules that intersect the requested area are selected
2. Efficient Loading - Only the portions of granules needed are loaded
3. Overview Support - Appropriate resolution levels are selected for efficiency
4. Heterogeneous CRS - Granules in different coordinate systems can be combined
5. Footprint Management - Precise granule shapes can be used instead of bounding boxes

Rendering System

The rendering system is responsible for converting GridCoverage objects into visual representations, applying styling and handling projection issues.

GridCoverageRenderer

The GridCoverageRenderer is the primary class responsible for rendering GridCoverages:

The renderer handles several complex tasks:

• Reprojection to the display CRS
• Handling edge cases like dateline crossing
• Advanced projection handling for global coverages
• Applying styling from SLD/CSS

Projection Handling

Rendering raster data across projections presents several challenges:

1. Dateline Crossing - Handling images that cross the 180° meridian
2. Polar Regions - Managing distortion near the poles
3. Global Data - Properly rendering worldwide datasets

GeoTools includes specialized projection handlers that manage these cases:

100%

The ProjectionHandler framework:

• Determines when special handling is needed
• Splits requests across the dateline when necessary
• Manages coordinate transformations for valid areas
• Recombines results from multiple requests

Advanced Features

NoData and ROI Handling

GeoTools provides sophisticated handling of NoData values (pixels with invalid or missing data) and Regions of Interest (ROIs):

• NoData values can be defined as single values or ranges
• ROIs can be created from vector geometries or raster masks
• Both can be propagated through processing chains
• They can be used together to define valid data areas

// Example of NoData and ROI handling
ImageWorker worker = new ImageWorker(sourceImage);
worker.setNoData(RangeFactory.create(-9999, -9999));  // Set NoData range
ROIGeometry roiGeometry = new ROIGeometry(geometry);  // Create ROI from geometry
worker.setROI(roiGeometry);  // Set ROI on the worker

Footprint Behavior

For image mosaics, footprints define the exact shape of each granule, allowing for precise control over which parts contribute to the final mosaic:

Footprint Mode	Behavior
None	Use the full bounding box of each granule
Cut	Clip granules to their footprint boundary
Transparent	Make areas outside the footprint transparent

Footprints can be defined as:

• Vector geometries stored in the catalog
• Raster masks derived from the data itself
• Computed on-the-fly based on valid data areas

Multithreaded Processing

GeoTools leverages multithreading in several areas of raster processing:

1. Parallel Granule Loading - Multiple granules can be loaded simultaneously
2. JAI TileScheduler - Parallel processing of image tiles
3. Concurrent Rendering - Multiple rendering operations can happen in parallel

// Example of configuring multithreading
Hints hints = new Hints();
ExecutorService threadPool = Executors.newFixedThreadPool(4);
hints.put(Hints.EXECUTOR_SERVICE, threadPool);
ImageMosaicReader reader = new ImageMosaicReader(source, hints);

The threading model is configurable through hints, allowing applications to control resource usage based on their requirements.

Conclusion

GeoTools' raster data processing system provides a comprehensive set of tools for working with geospatial raster data. From basic operations to advanced features like mosaicking and footprint management, the library supports a wide range of use cases for geospatial applications.

The modular design with specialized components for reading, processing, and rendering allows for flexibility and extensibility while maintaining a consistent API across different raster data formats and processing needs.