PixelGeoCoding (SNAP Engine API)

java.lang.Object
- org.esa.snap.core.datamodel.AbstractGeoCoding
- - org.esa.snap.core.datamodel.PixelGeoCoding

All Implemented Interfaces:

BasicPixelGeoCoding, GeoCoding
```
public class PixelGeoCoding
extends AbstractGeoCoding
implements BasicPixelGeoCoding
```
The PixelGeoCoding is an implementation of a GeoCoding which uses dedicated latitude and longitude bands in order to provide geographical positions for each pixel. Unlike the TiePointGeoCoding, which uses sub-sampled tie-point grids, the PixelGeoCoding class uses bands.
This class is especially useful for high accuracy geo-coding, e.g. if geographical positions are computed for each pixel by an upstream orthorectification.
While the implementation of the getGeoPos(PixelPos, GeoPos) is straight forward, the getPixelPos(GeoPos, PixelPos) uses two different search algorithms in order to find the corresponding geo-position for a given pixel:
1. Search an N x N window around an estimated pixel position using the geo-coding of the source product (if any) or
2. perform a quad-tree search if the source product has no geo-coding.
Use instances of this class with care: The constructor fully loads the data given by the latitudes and longitudes bands and the valid mask (if any) into memory.
Note (rq-20110526): A better implementation of the find pixel method could be something like:
1. Create a coverage of the source region by means of largely overlapping image tiles (e.g. tile size of 100 pixels squared with an overlap of 25 pixels)
2. For each tile create a rational function model of the (lon, lat) to (x, y) transformation, rotating to the (lon, lat) of the tile center
3. Refine the accuracy of the selected rational function model until the accuracy goal (i.e. a certain RMSE) is reached
4. Find all tiles {T1, T2, ...} that may include the (x, y) pixel coordinate of interest
5. Select the tile T in {T1, T2, ...} where the the (x, y) result is nearest to (0, 0)
6. Use the three closest pixels to compute the final (x, y)
7. Keep all rational function approximations in a map and reuse them for subsequent calls.
The advantage of this algorithm is that it obviously avoids problems related to the antimeridian and poles included in the source region.

Constructor Summary

Constructors
Constructor and Description
`PixelGeoCoding(Band latBand, Band lonBand, String validMask, int searchRadius)` Constructs a new pixel-based geo-coding.
`PixelGeoCoding(Band latBand, Band lonBand, String validMask, int searchRadius, ProgressMonitor pm)` Constructs a new pixel-based geo-coding.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canGetGeoPos()` Checks whether or not this geo-coding can determine the geodetic position from a pixel position.
`boolean`	`canGetPixelPos()` Checks whether or not this geo-coding can determine the pixel position from a geodetic position.
`void`	`dispose()` Releases all of the resources used by this object instance and all of its owned children.
`boolean`	`equals(Object o)`
`protected void`	`fillInvalidGaps(IndexValidator validator, float[] latElems, float[] lonElems, ProgressMonitor pm)` Fills the gaps in the given latitude and longitude data buffers.
`org.esa.snap.core.dataop.maptransf.Datum`	`getDatum()` Gets the datum, the reference point or surface against which `GeoPos` measurements are made.
`GeoPos`	`getGeoPos(PixelPos pixelPos, GeoPos geoPos)` Returns the latitude and longitude value for a given pixel co-ordinate.
`Band`	`getLatBand()`
`Band`	`getLonBand()`
`PixelPos`	`getPixelPos(GeoPos geoPos, PixelPos pixelPos)` Returns the pixel co-ordinates as x/y for a given geographical position given as lat/lon.
`GeoCoding`	`getPixelPosEstimator()` Gets the underlying geo-coding used as pixel position estimator.
`void`	`getPixelPosUsingEstimator(GeoPos geoPos, PixelPos pixelPos)` Returns the pixel co-ordinates as x/y for a given geographical position given as lat/lon.
`void`	`getPixelPosUsingQuadTreeSearch(GeoPos geoPos, PixelPos pixelPos)` Returns the pixel co-ordinates as x/y for a given geographical position given as lat/lon.
`static long`	`getRequiredMemory(Product product, boolean usesValidMask)` Computes an estimation of the memory required to create an instance of this class for the given product.
`int`	`getSearchRadius()` Gets the search radius used by this geo-coding.
`String`	`getValidMask()`
`int`	`hashCode()`
`boolean`	`isCrossingMeridianAt180()` Checks whether or not the longitudes of this geo-coding cross the +/- 180 degree meridian.
`boolean`	`transferGeoCoding(Scene srcScene, Scene destScene, ProductSubsetDef subsetDef)` Transfers the geo-coding of the `srcScene` to the `destScene` with respect to the given `subsetDef`.

Methods inherited from class org.esa.snap.core.datamodel.AbstractGeoCoding
createImageCRS, getGeoCRS, getImageCRS, getImageToMapTransform, getMapCRS, setGeoCRS, setImageCRS, setMapCRS

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.esa.snap.core.datamodel.GeoCoding
getGeoCRS, getImageCRS, getImageToMapTransform, getMapCRS

- Constructor Detail
  - PixelGeoCoding
```
public PixelGeoCoding(Band latBand,
                      Band lonBand,
                      String validMask,
                      int searchRadius)
```
    Constructs a new pixel-based geo-coding.
    Use with care: In contrast to the other constructor this one loads the data not until first access to getPixelPos(GeoPos, PixelPos) or getGeoPos(PixelPos, GeoPos).
    
    Parameters:
    
    latBand - the band providing the latitudes
    
    lonBand - the band providing the longitudes
    
    validMask - the valid mask expression used to identify valid lat/lon pairs, e.g. "NOT l1_flags.DUPLICATED". Can be null if a valid mask is not used.
    
    searchRadius - the search radius in pixels, shall depend on the actual spatial scene resolution, e.g. for 300 meter pixels a search radius of 5 is a good choice. This parameter is ignored if the source product is not geo-coded.
  - PixelGeoCoding
```
public PixelGeoCoding(Band latBand,
                      Band lonBand,
                      String validMask,
                      int searchRadius,
                      ProgressMonitor pm)
               throws IOException
```
    Constructs a new pixel-based geo-coding.
    Use with care: This constructor fully loads the data given by the latitudes and longitudes bands and the valid mask (if any) into memory.
    
    Parameters:
    
    latBand - the band providing the latitudes
    
    lonBand - the band providing the longitudes
    
    validMask - the valid mask expression used to identify valid lat/lon pairs, e.g. "NOT l1_flags.DUPLICATED". Can be null if a valid mask is not used.
    
    searchRadius - the search radius in pixels, shall depend on the actual spatial scene resolution, e.g. for 300 meter pixels a search radius of 5 is a good choice. This parameter is ignored if the source product is not geo-coded.
    
    pm - a monitor to inform the user about progress
    
    Throws:
    
    IOException - if an I/O error occurs while additional data is loaded from the source product
- Method Detail
  - fillInvalidGaps
```
protected void fillInvalidGaps(IndexValidator validator,
                               float[] latElems,
                               float[] lonElems,
                               ProgressMonitor pm)
```
    Fills the gaps in the given latitude and longitude data buffers. The method shall fill in reasonable a latitude and longitude value at all positions where validator.validateIndex(pixelIndex) returns false.
    The default implementation uses the underlying estimator (if any) to find default values for the gaps.
    
    Parameters:
    
    validator - the pixel validator, never null
    
    latElems - the latitude data buffer in row-major order
    
    lonElems - the longitude data buffer in row-major order
    
    pm - a monitor to inform the user about progress
  - getRequiredMemory
```
public static long getRequiredMemory(Product product,
                                     boolean usesValidMask)
```
    Computes an estimation of the memory required to create an instance of this class for the given product. The estimation is returned in bytes.
    
    Returns:
    
    an estimation of the required memory in bytes
  - getLatBand
```
public Band getLatBand()
```
    Specified by:
    
    getLatBand in interface BasicPixelGeoCoding
  - getLonBand
```
public Band getLonBand()
```
    Specified by:
    
    getLonBand in interface BasicPixelGeoCoding
  - getValidMask
```
public String getValidMask()
```
    Specified by:
    
    getValidMask in interface BasicPixelGeoCoding
  - getPixelPosEstimator
```
public GeoCoding getPixelPosEstimator()
```
    Gets the underlying geo-coding used as pixel position estimator.
    
    Specified by:
    
    getPixelPosEstimator in interface BasicPixelGeoCoding
    
    Returns:
    
    the underlying delegate geo-coding, can be null
  - getSearchRadius
```
public int getSearchRadius()
```
    Gets the search radius used by this geo-coding.
    
    Specified by:
    
    getSearchRadius in interface BasicPixelGeoCoding
    
    Returns:
    
    the search radius in pixels
  - isCrossingMeridianAt180
```
public boolean isCrossingMeridianAt180()
```
    Checks whether or not the longitudes of this geo-coding cross the +/- 180 degree meridian.
    
    Specified by:
    
    isCrossingMeridianAt180 in interface GeoCoding
    
    Returns:
    
    true, if so
  - canGetPixelPos
```
public boolean canGetPixelPos()
```
    Checks whether or not this geo-coding can determine the pixel position from a geodetic position.
    
    Specified by:
    
    canGetPixelPos in interface GeoCoding
    
    Returns:
    
    true, if so
  - canGetGeoPos
```
public boolean canGetGeoPos()
```
    Checks whether or not this geo-coding can determine the geodetic position from a pixel position.
    
    Specified by:
    
    canGetGeoPos in interface GeoCoding
    
    Returns:
    
    true, if so
  - getPixelPos
```
public PixelPos getPixelPos(GeoPos geoPos,
                            PixelPos pixelPos)
```
    Returns the pixel co-ordinates as x/y for a given geographical position given as lat/lon.
    
    Specified by:
    
    getPixelPos in interface GeoCoding
    
    Parameters:
    
    geoPos - the geographical position as lat/lon.
    
    pixelPos - an instance of Point to be used as return value. If this parameter is null, the method creates a new instance which it then returns.
    
    Returns:
    
    the pixel co-ordinates as x/y
  - getPixelPosUsingEstimator
```
public void getPixelPosUsingEstimator(GeoPos geoPos,
                                      PixelPos pixelPos)
```
    Returns the pixel co-ordinates as x/y for a given geographical position given as lat/lon.
    
    Parameters:
    
    geoPos - the geographical position as lat/lon.
    
    pixelPos - the return value.
  - getPixelPosUsingQuadTreeSearch
```
public void getPixelPosUsingQuadTreeSearch(GeoPos geoPos,
                                           PixelPos pixelPos)
```
    Returns the pixel co-ordinates as x/y for a given geographical position given as lat/lon. This algorithm
    
    Parameters:
    
    geoPos - the geographical position as lat/lon.
    
    pixelPos - the return value
  - getGeoPos
```
public GeoPos getGeoPos(PixelPos pixelPos,
                        GeoPos geoPos)
```
    Returns the latitude and longitude value for a given pixel co-ordinate.
    
    Specified by:
    
    getGeoPos in interface GeoCoding
    
    Parameters:
    
    pixelPos - the pixel's co-ordinates given as x,y
    
    geoPos - an instance of GeoPos to be used as return value. If this parameter is null, the method creates a new instance which it then returns.
    
    Returns:
    
    the geographical position as lat/lon.
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - dispose
```
public void dispose()
```
    Releases all of the resources used by this object instance and all of its owned children. Its primary use is to allow the garbage collector to perform a vanilla job.
    This method should be called only if it is for sure that this object instance will never be used again. The results of referencing an instance of this class after a call to dispose() are undefined.
    
    Specified by:
    
    dispose in interface GeoCoding
  - transferGeoCoding
```
public boolean transferGeoCoding(Scene srcScene,
                                 Scene destScene,
                                 ProductSubsetDef subsetDef)
```
    Transfers the geo-coding of the srcScene to the destScene with respect to the given subsetDef.
    
    Specified by:
    
    transferGeoCoding in class AbstractGeoCoding
    
    Parameters:
    
    srcScene - the source scene
    
    destScene - the destination scene
    
    subsetDef - the definition of the subset, may be null
    
    Returns:
    
    true, if the geo-coding could be transferred.
  - getDatum
```
public org.esa.snap.core.dataop.maptransf.Datum getDatum()
```
    Gets the datum, the reference point or surface against which GeoPos measurements are made.
    
    Specified by:
    
    getDatum in interface GeoCoding
    
    Returns:
    
    the datum

Class PixelGeoCoding

Constructor Summary

Method Summary

Methods inherited from class org.esa.snap.core.datamodel.AbstractGeoCoding

Methods inherited from class java.lang.Object

Methods inherited from interface org.esa.snap.core.datamodel.GeoCoding

Constructor Detail

PixelGeoCoding

PixelGeoCoding

Method Detail

fillInvalidGaps

getRequiredMemory

getLatBand

getLonBand

getValidMask

getPixelPosEstimator

getSearchRadius

isCrossingMeridianAt180

canGetPixelPos

canGetGeoPos

getPixelPos

getPixelPosUsingEstimator

getPixelPosUsingQuadTreeSearch

getGeoPos

equals

hashCode

dispose

transferGeoCoding

getDatum