org.gridfour.interpolation

Class InterpolatorBSpline

java.lang.Object

org.gridfour.interpolation.InterpolatorBSpline

All Implemented Interfaces:

IRasterInterpolator

public class InterpolatorBSpline
extends Object
implements IRasterInterpolator

Performs interpolations over a raster (grid) data set using the classic B-Spline algorithm.

The B-Spline interpolation treats the input grid as representing a continuous, real-valued surface defined over a 2D coordinate plane. The input grid is specified as an one-dimensional array of floating point values given in row-major order. For purposes of interpolation, this class treats the rows and columns in the grid as having a uniform, unit spacing. While this approach is provides efficiency when computing interpolated values, an adjustment for row and column spacing is required when computing derivatives. This adjustment is discussed below.

Using and reusing an IntepolationResult object

In raster-based applications, it is common for applications to process gridded data sets containing a very large number of samples. Therefore this class is designed to operate efficiently across multiple operations. In particular, it allows an application to construct a single instance of the InterpolationResults class that can be reused across multiple interpolations. If the reference is not null (valid), the interpolate method populates it with the resulting computations and returns the same reference that was input. If the reference is null, the interpolate method constructs a new instance which is returned to the calling method. This approach avoids the overhead of constructing multiple objects.

At this time, however, there is some question about how significant this savings may be. In repeated tests performing 1 million interpolations over a 1000-by-1000 grid, the interpolator required 30 milliseconds when creating new result object for each operation and 20 milliseconds when reusing the result object. So in practice, the savings may be of limited value. However, the testing was not performed on systems in which the JVM was operating under conditions of heavy memory use. In cases where the heap memory grows large, reusing result objects may become important.

Row and Column Scale Factors

In order to produce meaningful computations for derivatives and surface normal vectors, it is necessary that the three coordinate axes (x, y, and z) used in the interpolation have a uniform scale. In other words, one unit of change in the coordinate system associated with the input (the row-column coordinates) should cover the same distance as one unit of change in the output coordinates. Thus, when computing derivatives or the surface normal, the interpolation method implemented by this class requires the specification “spacing” values for the rows and columns. These values allow the application to assign appropriate scales to the input grid and to treat the interpolation coordinate system as “isotropic” (eg. As having a uniform scale). The rowSpace and columnSpace specifications are required in order to produce meaningful results for surface normal and derivatives. If your application is only using the interpolated value, and you do not wish to compute derivatives, you may supply zeroes for these input. For testing purposes, you may also try specifying values of 1.0 for these inputs.

Constructor Summary

Constructors

Constructor and Description
InterpolatorBSpline()

Method Summary

Modifier and Type	Method and Description
InterpolationResult	interpolate(double row, double column, int nRowsInGrid, int nColumnsInGrid, float[] grid, double rowSpacing, double columnSpacing, InterpolationTarget target, InterpolationResult outputResult) Compute the interpolated value, the derivatives, and the normal vector to the surface at the specified grid coordinates.
double	interpolateValue(double row, double column, int nRowsInGrid, int nColumnsInGrid, float[] grid) Compute the interpolated value at the specified grid coordinates.
boolean	isInterpolationTargetSupported(InterpolationTarget target) Indicates whether the interpolation implementation supports the specified target.

Methods inherited from class java.lang.Object

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

Constructor Detail

InterpolatorBSpline

public InterpolatorBSpline()

Method Detail

interpolateValue

public double interpolateValue(double row,
                               double column,
                               int nRowsInGrid,
                               int nColumnsInGrid,
                               float[] grid)

Compute the interpolated value at the specified grid coordinates. Derivatives are not computed by this method.

The row and column specifications represent real-valued coordinates and may use non-integral values to indicate positions between sample points. The interpolation coordinates may be given for any point within the grid.

Specified by:

interpolateValue in interface IRasterInterpolator

Parameters:

row - a real-valued, potentially non-integral row coordinate

column - a real-valued, potentially non-integral column coordinate

nRowsInGrid - the number of rows in the input grid.

nColumnsInGrid - the number of columns in the input grid

grid - the input grid, given in row-major order

Returns:

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

interpolate

public InterpolationResult interpolate(double row,
                                       double column,
                                       int nRowsInGrid,
                                       int nColumnsInGrid,
                                       float[] grid,
                                       double rowSpacing,
                                       double columnSpacing,
                                       InterpolationTarget target,
                                       InterpolationResult outputResult)

Compute the interpolated value, the derivatives, and the normal vector to the surface at the specified grid coordinates.

The row and column specifications represent real-valued coordinates and may use non-integral values to indicate positions between sample points. The interpolation coordinates may be given for any point within the grid.

The row and column spacing parameters are necessary for this routine to compute derivatives and surface normal vectors. If derivatives are not required, the spacing parameters will be ignored and applications are free to supply zeroes.

Specified by:

interpolate in interface IRasterInterpolator

Parameters:

row - a real-valued, potentially non-integral row coordinate

column - a real-valued, potentially non-integral column coordinate

nRowsInGrid - the number of rows in the input grid.

nColumnsInGrid - the number of columns in the input grid

grid - the input grid, given in row-major order

rowSpacing - a scale factor required for computing derivatives, or zero if derivative and surface normal vector computations are not required

columnSpacing - a scale factor required for computing derivatives, or zero if derivative and surface normal vector computations are not required

target - indicates which product is required for the interpolation, including value, value and first derivative, or value and first and second derivatives.

outputResult - an instance to store the results, or null if the method should construct a new instance.

Returns:

a valid instance of InterpolationResult or a null reference. If a valid reference to a result object is specified as an input, that instance will be populated and returned. If a null is specified, a new object will be constructed.

isInterpolationTargetSupported

public boolean isInterpolationTargetSupported(InterpolationTarget target)

Indicates whether the interpolation implementation supports the specified target. Not all interpolation techniques support the production of first and second derivatives. So this method provides applications the ability to assess the capabilities of the interpolator.

Specified by:

isInterpolationTargetSupported in interface IRasterInterpolator

Parameters:

target - a valid enumeration value.

Returns:

true if the target is supported; otherwise, false.