org.esa.beam.framework.datamodel
Class PixelGeoCoding

java.lang.Object
  org.esa.beam.framework.datamodel.AbstractGeoCoding
      org.esa.beam.framework.datamodel.PixelGeoCoding

All Implemented Interfaces:

GeoCoding

public class PixelGeoCoding
extends AbstractGeoCoding

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

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, com.bc.ceres.core.ProgressMonitor pm)
Constructs a new pixel-based geo-coding.

Method Summary

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, com.bc.ceres.core.ProgressMonitor pm) Fills the gaps in the given latitude and longitude data buffers.
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.beam.framework.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

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,
                      com.bc.ceres.core.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,
                               com.bc.ceres.core.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()

getLonBand

public Band getLonBand()

getValidMask

public String getValidMask()

getPixelPosEstimator

public GeoCoding getPixelPosEstimator()

Gets the underlying geo-coding used as pixel position estimator.

Returns:

the underlying delegate geo-coding, can be null

getSearchRadius

public int getSearchRadius()

Gets the search radius used by this geo-coding.

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.

Returns:

true, if so

canGetPixelPos

public boolean canGetPixelPos()

Checks whether or not this geo-coding can determine the pixel position from a geodetic position.

Returns:

true, if so

canGetGeoPos

public boolean canGetGeoPos()

Checks whether or not this geo-coding can determine the geodetic position from a pixel position.

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.

Parameters:

geoPos - the geographical position as lat/lon.

pixelPos - an instance of Point to be used as retun 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 retun value

getGeoPos

public GeoPos getGeoPos(PixelPos pixelPos,
                        GeoPos geoPos)

Returns the latitude and longitude value for a given pixel co-ordinate.

Parameters:

pixelPos - the pixel's co-ordinates given as x,y

geoPos - an instance of GeoPos to be used as retun 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.

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 Datum getDatum()

Gets the datum, the reference point or surface against which GeoPos measurements are made.

Returns:

the datum