javax.media.jai
Class Warp

java.lang.Object
  extended byjavax.media.jai.Warp
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
WarpGrid, WarpPerspective, WarpPolynomial

public abstract class Warp
extends Object
implements Serializable

A description of an image warp.

The central method of a Warp is warpSparseRect(), which returns the source pixel positions for a specified (subdivided) rectangular region of the output.

As in the Interpolation class, pixel positions are represented using scaled integer coordinates, yielding subpixel accuracy but still allowing the use of integer arithmetic. The degree of precision is set by means of the getSubSampleBitsH() and getSubSampleBitsV parameters to the warpRect() method.

See Also:
Interpolation, WarpAffine, WarpGrid, WarpPerspective, WarpPolynomial, WarpQuadratic, WarpCubic, WarpGeneralPolynomial, WarpOpImage, Serialized Form

Constructor Summary
protected Warp()
          Default constructor.
 
Method Summary
 Point2D mapDestPoint(Point2D destPt)
          Computes the source point corresponding to the supplied point.
 Rectangle mapDestRect(Rectangle destRect)
          Computes a Rectangle that is guaranteed to enclose the region of the source that is required in order to produce a given rectangular output region.
 Point2D mapSourcePoint(Point2D sourcePt)
          Computes the destination point corresponding to the supplied point.
 Rectangle mapSourceRect(Rectangle sourceRect)
          Computes a rectangle that is guaranteed to enclose the region of the destination that can potentially be affected by the pixels of a rectangle of a given source.
 float[] warpPoint(int x, int y, float[] destRect)
          Computes the source subpixel position for a given destination pixel.
 int[] warpPoint(int x, int y, int subsampleBitsH, int subsampleBitsV, int[] destRect)
          Computes the source subpixel position for a given destination pixel.
 float[] warpRect(int x, int y, int width, int height, float[] destRect)
          Computes the source subpixel positions for a given rectangular destination region.
 int[] warpRect(int x, int y, int width, int height, int subsampleBitsH, int subsampleBitsV, int[] destRect)
          Computes the source subpixel positions for a given rectangular destination region.
abstract  float[] warpSparseRect(int x, int y, int width, int height, int periodX, int periodY, float[] destRect)
           This method is must be implemented in all concrete subclasses.
 int[] warpSparseRect(int x, int y, int width, int height, int periodX, int periodY, int subsampleBitsH, int subsampleBitsV, int[] destRect)
          Computes the source subpixel positions for a given rectangular destination region, subsampled with an integral period.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Warp

protected Warp()
Default constructor.

Method Detail

warpRect

public int[] warpRect(int x,
                      int y,
                      int width,
                      int height,
                      int subsampleBitsH,
                      int subsampleBitsV,
                      int[] destRect)
Computes the source subpixel positions for a given rectangular destination region. The destination region is specified using normal integral (full pixel) coordinates. The source positions returned by the method are specified in fixed point, subpixel coordinates using the subsampleBitsH and subsampleBitsV parameters.

The integral destination rectangle coordinates should be considered pixel indices. The continuous plane of pixels locates each pixel index at a half-pixel location. For example, destination pixel (0,0) is located at the real location (0.5, 0.5). Thus pixels are considered to have a dimension of (1.0 x 1.0) with their "energy" concentrated in a "delta function" at relative coordinates (0.5, 0.5).

Destination to source mappings must keep this (0.5, 0.5) pixel center in mind when formulating transformation functions. Given integral destination pixel indices as an input, the fractional source location, as calculated by functions X(xDst,yDst), Y(xDst,yDst) is given by:


     Xsrc = X(xDst+0.5, yDst+0.5) - 0.5
     Ysrc = Y(xDst+0.5, yDst+0.5) - 0.5

 

The subtraction of 0.5 in the above formula produces the source pixel indices (in fractional form) needed to implement the various types of interpolation algorithms.

All of the Sun-supplied warp mapping functions perform the above final subtraction, since they have no knowledge of what interpolation algorithm will be used by a WarpOpImage implementation.

As a convenience, an implementation is provided for this method that calls warpSparseRect(). Subclasses may wish to provide their own implementations for better performance.

Parameters:
x - The minimum X coordinate of the destination region.
y - The minimum Y coordinate of the destination region.
width - The width of the destination region. Must be positive.
height - The height of the destination region. Must be positive.
subsampleBitsH - The desired fixed-point precision of the output X coordinates. Must be positive.
subsampleBitsV - The desired fixed-point precision of the output Y coordinates. Must be positive.
destRect - An int array containing at least 2*width*height elements, or null. If null, a new array will be constructed.
Returns:
A reference to the destRect parameter if it is non-null, or a new int array of length 2*width*height otherwise.

warpRect

public float[] warpRect(int x,
                        int y,
                        int width,
                        int height,
                        float[] destRect)
Computes the source subpixel positions for a given rectangular destination region. The destination region is specified using normal integral (full pixel) coordinates. The source positions returned by the method are specified in floating point.

As a convenience, an implementation is provided for this method that calls warpSparseRect(). Subclasses may wish to provide their own implementations for better performance.

Parameters:
x - The minimum X coordinate of the destination region.
y - The minimum Y coordinate of the destination region.
width - The width of the destination region.
height - The height of the destination region.
destRect - A float array containing at least 2*width*height elements, or null. If null, a new array will be constructed.
Returns:
A reference to the destRect parameter if it is non-null, or a new float array of length 2*width*height otherwise.
Throws:
IllegalArgumentException - if destRect is too small.

warpPoint

public int[] warpPoint(int x,
                       int y,
                       int subsampleBitsH,
                       int subsampleBitsV,
                       int[] destRect)
Computes the source subpixel position for a given destination pixel. The destination pixel is specified using normal integral (full pixel) coordinates. The source position returned by the method is specified in fixed point, subpixel coordinates using the subsampleBitsH and subsampleBitsV parameters.

As a convenience, an implementation is provided for this method that calls warpSparseRect(). Subclasses may wish to provide their own implementations for better performance.

Parameters:
x - The minimum X coordinate of the destination region.
y - The minimum Y coordinate of the destination region.
subsampleBitsH - The desired fixed-point precision of the output X coordinates.
subsampleBitsV - The desired fixed-point precision of the output Y coordinates.
destRect - An int array containing at least 2 elements, or null. If null, a new array will be constructed.
Returns:
A reference to the destRect parameter if it is non-null, or a new int array of length 2 otherwise.
Throws:
IllegalArgumentException - if destRect is too small.

warpPoint

public float[] warpPoint(int x,
                         int y,
                         float[] destRect)
Computes the source subpixel position for a given destination pixel. The destination pixel is specified using normal integral (full pixel) coordinates. The source position returned by the method is specified in floating point.

As a convenience, an implementation is provided for this method that calls warpSparseRect(). Subclasses may wish to provide their own implementations for better performance.

Parameters:
x - The minimum X coordinate of the destination region.
y - The minimum Y coordinate of the destination region.
destRect - A float array containing at least 2 elements, or null. If null, a new array will be constructed.
Returns:
A reference to the destRect parameter if it is non-null, or a new float array of length 2 otherwise.
Throws:
IllegalArgumentException - if destRect is too small.

warpSparseRect

public int[] warpSparseRect(int x,
                            int y,
                            int width,
                            int height,
                            int periodX,
                            int periodY,
                            int subsampleBitsH,
                            int subsampleBitsV,
                            int[] destRect)
Computes the source subpixel positions for a given rectangular destination region, subsampled with an integral period. The destination region is specified using normal integral (full pixel) coordinates. The source positions returned by the method are specified in fixed point, subpixel coordinates using the subsampleBitsH and subsampleBitsV parameters.

As a convenience, an implementation is provided for this method that calls warpSparseRect() with a float destRect parameter. Subclasses may wish to provide their own implementations for better performance.

Parameters:
x - the minimum X coordinate of the destination region.
y - the minimum Y coordinate of the destination region.
width - the width of the destination region.
height - the height of the destination region.
periodX - the horizontal sampling period.
periodY - the horizontal sampling period.
subsampleBitsH - The desired fixed-point precision of the output X coordinates.
subsampleBitsV - The desired fixed-point precision of the output Y coordinates.
destRect - An int array containing at least 2*((width+periodX-1)/periodX)*((height+periodY-1)/periodY) elements, or null. If null, a new array will be constructed.
Returns:
A reference to the destRect parameter if it is non-null, or a new int array otherwise.
Throws:
IllegalArgumentException - if destRect is too small.

warpSparseRect

public abstract float[] warpSparseRect(int x,
                                       int y,
                                       int width,
                                       int height,
                                       int periodX,
                                       int periodY,
                                       float[] destRect)

This method is must be implemented in all concrete subclasses.

Parameters:
x - The minimum X coordinate of the destination region.
y - The minimum Y coordinate of the destination region.
width - The width of the destination region.
height - The height of the destination region.
periodX - The horizontal sampling period.
periodY - The vertical sampling period.
destRect - A float array containing at least 2*((width+periodX-1)/periodX)* ((height+periodY-1)/periodY) elements, or null. If null, a new array will be constructed.
Returns:
a reference to the destRect parameter if it is non-null, or a new float array otherwise.

mapSourceRect

public Rectangle mapSourceRect(Rectangle sourceRect)
Computes a rectangle that is guaranteed to enclose the region of the destination that can potentially be affected by the pixels of a rectangle of a given source. Unlike the corresponding WarpOpImage method, this routine may return null if it is infeasible to compute such a bounding box.

The default implementation in this class returns null.

Parameters:
sourceRect - The Rectangle in source coordinates.
Returns:
A Rectangle in the destination coordinate system that enclose the region that can potentially be affected by the pixels of a rectangle of a given source, or null.

mapDestRect

public Rectangle mapDestRect(Rectangle destRect)
Computes a Rectangle that is guaranteed to enclose the region of the source that is required in order to produce a given rectangular output region.

Parameters:
destRect - The Rectangle in destination coordinates.
Returns:
A Rectangle in the source coordinate system that is guaranteed to contain all pixels referenced by the output of warpRect() on the destination region, or null.
Throws:
IllegalArgumentException - if destRect is null.

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:

 float[] sourceXY = warpSparseRect((int)destPt.getX(),
                                   (int)destPt.getY(),
                                   1, 1, 1, 1, null);
 Point2D pt = (Point2D)destPt.clone();
 pt.setLocation(sourceXY[0], sourceXY[1]);
 
Subclasses requiring different behavior should override this method. This would be the case for those which desire a more precise mapping.

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

mapSourcePoint

public Point2D mapSourcePoint(Point2D sourcePt)
Computes the destination point corresponding to the supplied point.

This method returns null. Subclasses requiring different behavior should override this method.

Parameters:
sourcePt - the position in source image coordinates to map to destination image coordinates.
Returns:
null.
Throws:
IllegalArgumentException - if sourcePt is null.
Since:
JAI 1.1.2