org.gridfour.gvrs

Class GvrsInterpolatorBSpline

java.lang.Object

org.gridfour.gvrs.GvrsInterpolatorBSpline

public class GvrsInterpolatorBSpline
extends Object

Performs interpolations over a GVRS raster file using the classic B-Spline algorithm. This class combines access routines for extracting sample data from GVRS raster files with the general-purpose InterpolatorBSpline.java class implemented as part of the Gridfour software library.

For geographic coordinates, logic is implemented to support cases where the interpolated values span the coordinate-system division (usually at +/-180 degrees longitude)

This class is intended to be used for applications that may require millions of calculations. Therefore, emphasis has been placed on speed.

The coordinate systems used for interpolation are described in the Gridfour project wiki article Gridfour Raster Index and Coordinate Systems. The article includes a discussion of the concept of a "fringe" region at the periphery of the interpolation domain.

Constructor Summary

Constructors

Constructor and Description
GvrsInterpolatorBSpline(GvrsElement element) Constructs an instance that will operate over the specified GVRS File.

Method Summary

Modifier and Type	Method and Description
double	z(double x, double y) Interpolates a value for the specified x and y coordinates.
double	zInterpGrid(double row, double column) Interpolate the value at the specified grid coordinates.
InterpolationResult	zNormal(double x, double y) Interpolates a value at the indicated position and also computes the unit surface normal vector.
InterpolationResult	zNormalGrid(double row, double column) Interpolates a value at the indicated position and also computes the unit surface normal vector.
double	zTest(double x, double y, int index) A test method to perform a simple bi-linear interpolation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GvrsInterpolatorBSpline

public GvrsInterpolatorBSpline(GvrsElement element)
                        throws IOException

Constructs an instance that will operate over the specified GVRS File.

Parameters:

element - a valid GVRS element from a file opened for read access.

Throws:

IOException - in the event of an I/O error

Method Detail

z

public double z(double x,
                double y)
         throws IOException

Interpolates a value for the specified x and y coordinates.

In the event that the coordinates are taken from a geographic coordinate system, it is assumed that the x coordinate gives a longitude and that the y coordinate gives a latitude value. Thus the order of arguments for this method would be

     longitude, latitude
 

This approach is a departure from that used in other parts of the Gridfour API.

Parameters:

x - the x coordinate for interpolation

y - the y coordinate for interpolation

Returns:

if successful, a valid floating point number; otherwise, a NaN.

Throws:

IOException - in the event of an IO error

zNormal

public InterpolationResult zNormal(double x,
                                   double y)
                            throws IOException

Interpolates a value at the indicated position and also computes the unit surface normal vector. Intended for rendering purposes.

In the event that the coordinates are taken from a geographic coordinate system, it is assumed that the x coordinate gives a longitude and that the y coordinate gives a latitude value. Thus the order of arguments for this method would be

 longitude, latitude
 

This approach is a departure from that used in other parts of the Gridfour API.

The result is stored in instance of the IterpolationResult class.

This method may throw an IllegalArgumentException if the specified coordinates are out-of-bounds.

The first derivatives computed by this method are based on the model coordinate system specified by the GvrsFile instance that was used to construct this class. For Geographic coordinates, the angular cell spacing (given in degrees) is converted to meters. So, for example, a partial derivative for a surface giving elevation in meters z = f(x, y) would be unitless tangents (dz/dx, dz/dy) with the units of change in elevation being cancelled out by the units of change in distance. While this approach is imperfect, it is what is used at this stage of the Gridfour software's development. Note, also, that for geographic models, the X scale across columns is adjusted according to the latitude specified for the interpolation point (to account for the convergence of the meridians).

Parameters:

x - the x coordinate for interpolation

y - the y coordinate for interpolation

Returns:

An instance of InterpolationResult.

Throws:

IOException - in the event of an IO error.

zNormalGrid

public InterpolationResult zNormalGrid(double row,
                                       double column)
                                throws IOException

Interpolates a value at the indicated position and also computes the unit surface normal vector. Intended for rendering purposes.

In the event that the coordinates are taken from a geographic coordinate system, it is assumed that the x coordinate gives a longitude and that the y coordinate gives a latitude value.

The result is stored in instance of the IterpolationResult class.

This method may throw an IllegalArgumentException if the specified coordinates are out-of-bounds.

The first derivatives computed by this method are based on the model coordinate system specified by the GvrsFile instance that was used to construct this class. For Geographic coordinates, the angular cell spacing (given in degrees) is converted to meters. So, for example, a partial derivative for a surface giving elevation in meters z = f(x, y) would be unitless tangents (dz/dx, dz/dy) with the units of change in elevation being cancelled out by the units of change in distance. While this approach is imperfect, it is what is used at this stage of the Gridfour software's development. Note, also, that for geographic models, the X scale across columns is adjusted according to the latitude specified for the interpolation point (to account for the convergence of the meridians).

Parameters:

row - coordinate for interpolation, not necessarily integral

column - coordinate for interpolation, not necessarily integral

Returns:

An instance of InterpolationResult.

Throws:

IOException - in the event of an IO error.

zInterpGrid

public double zInterpGrid(double row,
                          double column)
                   throws IOException

Interpolate the value at the specified grid coordinates. Note that grid coordinates are not restricted to integral values but may specify points between sample points (thus requiring an interpolation).

Parameters:

row - the row coordinate for the interpolation point

column - the column coordinate for the interpolation point

Returns:

if successful, a valid interpolation value; otherwise, the fill value for this element.

Throws:

IOException - in the event of a non-recoverable I/O exception

zTest

public double zTest(double x,
                    double y,
                    int index)
             throws IOException

A test method to perform a simple bi-linear interpolation. Used for comparing results with the standard interpolation

Parameters:

x - the x coordinate of the interpolation point

y - the y coordinate of the interpolation point

index - a value in the range 0 to dimension-1, giving the index for the data element to be retrieved.

Returns:

if successful, a valid floating point value; otherwise, NaN

Throws:

IOException - in the event of an IO error