javax.media.jai
Class WarpPolynomial

java.lang.Object
  |
  +--javax.media.jai.Warp
        |
        +--javax.media.jai.WarpPolynomial
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
WarpAffine, WarpCubic, WarpGeneralPolynomial, WarpQuadratic

public abstract class WarpPolynomial
extends Warp

A polynomial-based description of an image warp.

The mapping is defined by two bivariate polynomial functions X(x, y) and Y(x, y) that map destination (x, y) coordinates to source X and Y positions respectively

The functions X(x, y) and Y(x, y) have the form:

 SUM{i = 0 to n} {SUM{j = 0 to i}{a_ij*x^(i - j)*y^j}}

 where n is the degree os the polynomial
 

WarpAffine, WarpQuadratic, and WarpCubic are special cases of WarpPolynomial for n equal to 1, 2, and 3 respectively. WarpGeneralPolynomial provides a concrete implementation for polynomials of higher degree.

See Also:
WarpAffine, WarpQuadratic, WarpCubic, WarpGeneralPolynomial, Serialized Form

Field Summary
protected  int degree
          The degree of the polynomial, determined by the number of coefficients supplied via the X and Y coefficients arrays.
protected  float postScaleX
          A scaling factor applied to the result of the X polynomial evaluation which compensates for the input scaling, so that the correctly scaled result is obtained.
protected  float postScaleY
          A scaling factor applied to the result of the Y polynomial evaluation which compensates for the input scaling, so that the correctly scaled result is obtained.
protected  float preScaleX
          A scaling factor applied to input (dest) x coordinates to improve computational accuracy.
protected  float preScaleY
          A scaling factor applied to input (dest) y coordinates to improve computational accuracy.
protected  float[] xCoeffs
          An array of coefficients that maps a destination point to the source's X coordinate.
protected  float[] yCoeffs
          An array of coefficients that maps a destination point to the source's Y coordinate.
 
Constructor Summary
WarpPolynomial(float[] xCoeffs, float[] yCoeffs)
          Constructs a WarpPolynomial with pre- and post-scale factors of 1.
WarpPolynomial(float[] xCoeffs, float[] yCoeffs, float preScaleX, float preScaleY, float postScaleX, float postScaleY)
          Constructs a WarpPolynomial with a given transform mapping destination pixels into source space.
 
Method Summary
static WarpPolynomial createWarp(float[] sourceCoords, int sourceOffset, float[] destCoords, int destOffset, int numCoords, float preScaleX, float preScaleY, float postScaleX, float postScaleY, int degree)
          Returns an instance of WarpPolynomial or its subclasses that approximately maps the given scaled destination image coordinates into the given scaled source image coordinates.
 float[][] getCoeffs()
          Returns the raw coefficients array for both the X and Y coordinate mapping.
 int getDegree()
          Returns the degree of the warp polynomials.
 float getPostScaleX()
          Returns the scaling factor applied to the result of the X polynomial.
 float getPostScaleY()
          Returns the scaling factor applied to the result of the Y polynomial.
 float getPreScaleX()
          Returns the scaling factor applied to input (dest) X coordinates.
 float getPreScaleY()
          Returns the scaling factor applied to input (dest) Y coordinates.
 float[] getXCoeffs()
          Returns the raw coefficients array for the X coordinate mapping.
 float[] getYCoeffs()
          Returns the raw coefficients array for the Y coordinate mapping.
 Point2D mapDestPoint(Point2D destPt)
          Computes the source point corresponding to the supplied point.
 
Methods inherited from class javax.media.jai.Warp
mapDestRect, mapSourcePoint, mapSourceRect, warpPoint, warpPoint, warpRect, warpRect, warpSparseRect, warpSparseRect
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

xCoeffs

protected float[] xCoeffs
An array of coefficients that maps a destination point to the source's X coordinate.

yCoeffs

protected float[] yCoeffs
An array of coefficients that maps a destination point to the source's Y coordinate.

preScaleX

protected float preScaleX
A scaling factor applied to input (dest) x coordinates to improve computational accuracy.

preScaleY

protected float preScaleY
A scaling factor applied to input (dest) y coordinates to improve computational accuracy.

postScaleX

protected float postScaleX
A scaling factor applied to the result of the X polynomial evaluation which compensates for the input scaling, so that the correctly scaled result is obtained.

postScaleY

protected float postScaleY
A scaling factor applied to the result of the Y polynomial evaluation which compensates for the input scaling, so that the correctly scaled result is obtained.

degree

protected int degree
The degree of the polynomial, determined by the number of coefficients supplied via the X and Y coefficients arrays.
Constructor Detail

WarpPolynomial

public WarpPolynomial(float[] xCoeffs,
                      float[] yCoeffs,
                      float preScaleX,
                      float preScaleY,
                      float postScaleX,
                      float postScaleY)
Constructs a WarpPolynomial with a given transform mapping destination pixels into source space. Note that this is a backward mapping as opposed to the forward mapping used in AffineOpImage.

The xCoeffs and yCoeffs parameters must contain the same number of coefficients of the form (n + 1)(n + 2)/2 for some n, where n is the non-negative degree power of the polynomial. The coefficients, in order, are associated with the terms:

 1, x, y, x^2, x*y, y^2, ..., x^n, x^(n - 1)*y, ..., x*y^(n - 1), y^n
 
and coefficients of value 0 cannot be omitted.

The source (x, y) coordinate is pre-scaled by the factors preScaleX and preScaleY prior to the evaluation of the polynomial. The result of the polynomial evaluations are scaled by postScaleX and postScaleY to produce the destination pixel coordinates. This process allows for better precision of the results.

Parameters:
xCoeffs - The destination to source transform coefficients for the X coordinate.
yCoeffs - The destination to source transform coefficients for the Y coordinate.
preScaleX - The scale factor to apply to input (dest) X positions.
preScaleY - The scale factor to apply to input (dest) Y positions.
postScaleX - The scale factor to apply to the X polynomial output.
postScaleY - The scale factor to apply to the Y polynomial output.
Throws:
IllegalArgumentException - if xCoeff or yCoeff have an illegal number of entries.

WarpPolynomial

public WarpPolynomial(float[] xCoeffs,
                      float[] yCoeffs)
Constructs a WarpPolynomial with pre- and post-scale factors of 1.
Parameters:
xCoeffs - The destination to source transform coefficients for the X coordinate.
yCoeffs - The destination to source transform coefficients for the Y coordinate.
Method Detail

getXCoeffs

public float[] getXCoeffs()
Returns the raw coefficients array for the X coordinate mapping.
Returns:
A cloned array of floats giving the polynomial coefficients for the X coordinate mapping.

getYCoeffs

public float[] getYCoeffs()
Returns the raw coefficients array for the Y coordinate mapping.
Returns:
A cloned array of floats giving the polynomial coefficients for the Y coordinate mapping.

getCoeffs

public float[][] getCoeffs()
Returns the raw coefficients array for both the X and Y coordinate mapping.
Returns:
A cloned two-dimensional array of floats giving the polynomial coefficients for the X and Y coordinate mapping.

getPreScaleX

public float getPreScaleX()
Returns the scaling factor applied to input (dest) X coordinates.

getPreScaleY

public float getPreScaleY()
Returns the scaling factor applied to input (dest) Y coordinates.

getPostScaleX

public float getPostScaleX()
Returns the scaling factor applied to the result of the X polynomial.

getPostScaleY

public float getPostScaleY()
Returns the scaling factor applied to the result of the Y polynomial.

getDegree

public int getDegree()
Returns the degree of the warp polynomials.
Returns:
The degree as an int.

createWarp

public static WarpPolynomial createWarp(float[] sourceCoords,
                                        int sourceOffset,
                                        float[] destCoords,
                                        int destOffset,
                                        int numCoords,
                                        float preScaleX,
                                        float preScaleY,
                                        float postScaleX,
                                        float postScaleY,
                                        int degree)
Returns an instance of WarpPolynomial or its subclasses that approximately maps the given scaled destination image coordinates into the given scaled source image coordinates. The mapping is given by:
 x' = postScaleX*(xpoly(x*preScaleX, y*preScaleY));
 x' = postScaleY*(ypoly(x*preScaleX, y*preScaleY));
 

Typically, it is useful to set preScaleX to 1.0F/destImage.getWidth() and postScaleX to srcImage.getWidth() so that the input and output of the polynomials lie between 0 and 1.

The degree of the polynomial is supplied as an argument.

Parameters:
sourceCoords - An array of floats containing the source coordinates with X and Y alternating.
sourceOffset - the initial entry of sourceCoords to be used.
destCoords - An array of floats containing the destination coordinates with X and Y alternating.
destOffset - The initial entry of destCoords to be used.
numCoords - The number of coordinates from sourceCoords and destCoords to be used.
preScaleX - The scale factor to apply to input (dest) X positions.
preScaleY - The scale factor to apply to input (dest) Y positions.
postScaleX - The scale factor to apply to X polynomial output.
postScaleY - The scale factor to apply to the Y polynomial output.
degree - The desired degree of the warp polynomials.
Returns:
An instance of WarpPolynomial.
Throws:
IllegalArgumentException - if arrays sourceCoords or destCoords are too small

mapDestPoint

public Point2D mapDestPoint(Point2D destPt)
Computes the source point corresponding to the supplied point.

This method returns the value of pt in the following code snippet:

 double dx = (destPt.getX() + 0.5)*preScaleX;
 double dy = (destPt.getY() + 0.5)*preScaleY;

 double sx = 0.0;
 double sy = 0.0;
 int c = 0;

 for(int nx = 0; nx <= degree; nx++) {
     for(int ny = 0; ny <= nx; ny++) {
         double t = Math.pow(dx, nx - ny)*Math.pow(dy, ny);
         sx += xCoeffs[c] * t;
         sy += yCoeffs[c] * t;
         c++;
     }
 }

 Point2D pt = (Point2D)destPt.clone();
 pt.setLocation(sx*postScaleX - 0.5, sy*postScaleY - 0.5);
 

Overrides:
mapDestPoint in class Warp
Parameters:
destPt - the position in destination image coordinates to map to source image coordinates.
Returns:
a Point2D of the same class as destPt.
Throws:
IllegalArgumentException - if destPt is null.
Since:
JAI 1.1.2