Framework and Functionality

The idea behind the ComponentGeoCoding is to provide a variable set of well tested building blocks that allow to define a geo-coding optimally adapted to the dataset. 

Open

The geo-coding can be assembled from a catalogue of components, which can be configured to match the data. The geo-coding object separates the construction and initialisation phase. This allows SNAP code to create a configured geo-coding early and initialize, which means loading and analysing the raster data, at a later point, when the data is requested.

Classes and Interfaces

ComponentGeoCoding 

This class bundles the functionality of the geo-coding. It contains a ForwardCoding and an InverseCoding class, and some utility methods e.g. to transfer the geocoding and a means to clean up resources used. This class implements the only interface used to interact with the geo-coding, the interface org.esa.snap.core.datamodel.GeoCoding. 

It implements initialize() to separate construction from initialization phase. 

code -> 

ForwardCoding 

This interface defines the contract for a ForwardCoding implementation, i.e.  transformation that returns the geo-position for a specific pixel position inside the raster. The available components are described below. 

All algorithm classes implement initialize() to separate construction from initialization phase. 

code-> 

InverseCoding 

The opposite interface: it defines the contract for an InverseCoding implementation. This is the inverse transform that returns a pixel position for a given geo-position, or an invalid value, if the geo position is not contained in the raster. The available components are described further below. 

All algorithm classes implement initialize() to separate construction from initialization phase. 

code-> 

GeoRaster

This container class bundles all resources and configuration elements that a GeoCoding requires to be fully configured. These are: 

• Raster dimensions and scene dimensions 

• Ground resolution 

• Subsampling and offset factors 

• The data for longitude and latitude as floating-point arrays 

• Longitude and latitude variable names 

code-> 

ForwardCoding Implementations

PixelForward

This is a simple ForwardCoding that uses a full resolution geocoding raster, i.e. one measurement pixel is associated to one geo-position. For any given (x/y) it returns the associated (lon/lat) stored at this raster position. Raster positions on fractional positions are rounded to the nearest integer x or y position. If the (x/y) position is not inside the measurement raster, it returns an invalid geo-position object. 

code -> 

PixelInterpolatingForward 

Another ForwardCoding that uses a full resolution raster, this implementation interpolates the geo-location between the closest four pixels, identified by the fractional part of the pixel locations. Thus, returning a simple oversampled geo-location wrt. the original resolution. The anti-meridian is being taken into account during the interpolation calculations. If the (x/y) position is not inside the measurement raster, it returns an invalid geo-position object. 

code -> 

TiePointBilinearForward

This forward coding operates on subsampled geo-location data, so called tie point rasters. If a requested geo-location at a (x/y) position does not map directly to a tie point raster position, the geolocation will be interpolated using a bilinear algorithm. The anti-meridian is being taken into account during the interpolation calculations. If the (x/y) position is not inside the measurement raster, it returns an invalid geo-position object. 

code -> 

TiePointSplineForward

This forward coding operates on subsampled geo-location data, too. If a requested geo-location at a (x/y) position does not map directly to a tie point raster position, the geolocation will be interpolated using a spline algorithm. The anti-meridian is being taken into account during the interpolation calculations. If the (x/y) position is not inside the measurement raster, it returns an invalid geo-position object. 

code ->

InverseCoding Implementations 

The inverse geo-coding problem can be broken down to finding the closest (x/y) location to the given geo-location. Three different algorithms are available for selection: 

PixelQuadTreeInverse

This inverse coding operates on full raster geo-location data. It finds the closes target location by applying a quad-tree decomposition of the data. Optionally, the raster location can be interpolated to sub-pixel accuracy. The anti-meridian and the poles are being considered during the decomposition calculations. If the (lon/lat) position is not inside the measurement raster, it returns an invalid pixel-position object. 

code -> 

PixelGeoIndexInverse

This inverse coding operates on full raster geo-location data, too. It finds the closest target location by applying a geo-index-based search. This class requires significantly more time to initialize than the quad-tree due to the construction of the geo-index, but the index lookup is much faster, scaling with log(n). Optionally, the raster location can be interpolated to sub-pixel accuracy. The anti-meridian and the poles are being taken into account during the index calculations. If the (lon/lat) position is not inside the measurement raster, it returns an invalid pixel-position object. 

code -> 

TiePointInverse

This inverse coding operates on sub-sampled geo-location data. It uses a best approximation approach up to polynoms of order three to calculate the inverse transformation. The anti-meridian and the poles are being taken into account during the index calculations. If the (lon/lat) position is not inside the measurement raster, it returns an invalid pixel-position object. 

code ->

API

Construction

A ComponentGeoCoding requires at least three parameters during construction. These are the forward and inverse coding classes and the information container for the input datasets. 

ComponentGeoCoding(GeoRaster geoRaster, ForwardCoding forwardCoding, InverseCoding inverseCoding) 

Either forwardCoding or inverseCoding can be null, if a one-directional GeoCoding shall be constructed. There exist several constructors with different parameter sets. Additional parameters can be chosen from  

• GeoChecks – defines the set of checks to be executed on initialize. Can be none or any of “ANTIMERIDIAN, POLES”. 

• CoordinateReferenceSystem – define a CRS 

After construction, the object is in a “prepared” state, waiting for the initialization call to run the initialization tasks and activate. 

The GeoRaster parameter must contain the following entities: 

• longitudes, latitudes – double precision geo-location data 

• lonVariableName, latVariableName – the geo-location variable names 

• rasterWidth, rasterHeight – the data dimension 

• rasterResolutionInKm – ground resolution, required for pole treatment 

During the initialisation, the set-up for the geo-coding is executed, depending on the GeoCheck parameter setting. This includes a check for the existence of the geo-features and the adaptation of the algorithms accordingly. 

A full code example, embedded in a complex product reader environment is available in the Sentinel-3 reader. Sentinel3Level1Reader.java 

Also, a convenience factory exists that covers common code construction details, exposing factory methods with simple interfaces. GeoCodingFactory.java 

Usage

The ComponentGeoCoding is used in the same way as all other GeoCoding implementations. The methods 

PixelPos getPixelPos(final GeoPos geoPos, PixelPos pixelPos) 

GeoPos getGeoPos(final PixelPos pixelPos, GeoPos geoPos) 

expose the standard interface. Several getter methods exist to request status information from the geo-coding or offer utility methods, check the JavaDoc for a detailed description. GeoCoding.java 

Serialisation

Utility classes exist that allow serializing/de-serialising of the ComponentGeoCoding parametrisation. This allows to store and retrieve the intended geocoding with the data as SNAP specific meta-datum. The class org.esa.snap.core.dataio.geocoding.ComponentGeoCodingPersistenceConverter connects to the appropriate serialization framework using the Services API. An example on the usage can be found in the DIMAP file format code: DimapProductHelpers.java 

The complete Technical Note delivered to ESA can be downloaded from here:

Open