vwarp(1)

PROGRAM
vwarp - Perform polynomial geometric transformation (warp)

SYNTAX

vwarp

-i1 input image

-i2 X polynomial coefficients image

-i3 Y polynomial coefficients image

-o  output image

[-x]
    x coordinate of center-of-action

[-y]
    y coordinate of center-of-action

[-V]
    Gives the version for vwarp

[-U]
    Gives the usage for vwarp

[-P]
    Prompts for command line options

[-A [file1]]
    Creates the answer file called vwarp.ans or file1

[-a [file1]]
    Uses vwarp.ans or file1 as the answer file

DESCRIPTION
vwarp is used to alter the spatial properties of an image by performing a transformation in which the old coordinates of a pixel are mapped to a new location by a polynomial relationship. The old coordinates, (x,y) are related to the new coordinates (x',y') by the following relations (for n=2):
    x` = A[0,0]*1 + A[1,0]*x + A[2,0]*x^2
       + A[0,1]*y + A[1,1]*x*y + A[2,1]*x^2*y
       + A[0,2]*y^2 + A[1,2]*x*y^2 + A[2,2]*x^2*y^2
    y` = B[0,0]*1 + B[1,0]*x + B[2,0]*x^2
       + B[0,1]*y + B[1,1]*x*y + B[2,1]*x^2*y
       + B[0,2]*y^2 + B[1,2]*x*y^2 + B[2,2]*x^2*y^2

Note that the new coordinates can be expressed as a sum of terms where the coefficients can be arranged in the following matrix:
           1 x x^2 x^3 x^4 --- x^n
      1 A[0,0] A[1,0] A[2,0] A[3,0] A[4,0] A[n,0]
      y A[0,1] A[1,1] A[2,1] A[3,1] A[4,1] A[n,1]
      y^2 A[0,2] A[1,2] A[2,2] A[3,2] A[4,2] A[n,2]
      y^3 A[0,3] A[1,3] A[2,3] A[3,3] A[4,3] A[n,3]
      y^4 A[0,4] A[1,4] A[2,4] A[3,4] A[4,4] A[n,4]
      |
      y^n A[0,n] A[1,n] A[2,n] A[3,n] A[4,n] A[n,n]

where the contribution to the polynomial is given by multiplying the coefficient by the product of the raised terms along the top and left side of the matrix.

The coefficients for the the two polynomials (one for x and one for y) are supplied to vwarp in the form of small images, the dimensions of which determine the order of the polynomials. The two coefficient images can be easily created by hand with the use of vcustom(1). All data types except COMPLEX and transforms can be used as coefficient images.

The output image is formed by mapping each individual rectangular region in the input image (composed of four neighboring pixels) through the transform and onto the output plane in the form of a polygon. The polygon is filled onto the output plane using scan-line bilinear interpolation. Note that it is possible to distort mapping so severely that the input rectangle can be mapped onto a triangle, line, point, twisted hourglass, etc. All of these cases are resolved except for the hourglass case. Also note that it may be possible to transform into a space that you cannot get back from (i.e. the above matrices have no inverses). If you intend to get tricky here, you should brush up on your linear transforms and matrix theory (good book: Golub and VanLoan, Matrix Computations).

The point called the center-of-action is the point that is specified as the origin of the spatial coordinates prior to applying the transform. The output plane is then shifted so that its origin lies at that same specified point. The end result is like specifying what point to put under a magnifying glass. When using coefficients supplied by vbilinco(1) the center of action should be left at zero, which is the default.

The code looks at the coefficient matrices and constructs lists of non-zero coefficients and the corresponding power terms. Only non-zero power terms are computed, so it should not cost too much to have large matrices as long as they're sparse.

As a final note, look out for transforms that use only even powers of the coordinates when the center-of-action is at other then [0,0]. The transform will take negative distances and make them positive (a well known characteristic of even powers of a number). Since the input plane is scanned left to right, and top to bottom, it is possible to overwrite part of the output plane with one or more regions of the input plane! The result in this case depends on which part was looked at first by the scanning loop. No answer is right, so you get one of the many approximations.

REQUIRED ARGUMENTS

-i1 type: infile
    desc: input image

-i2 type: infile
    desc: X polynomial coefficients image

-i3 type: infile
    desc: Y polynomial coefficients image

-o  type: outfile
    desc: output image

OPTIONAL ARGUMENTS

-x  type: float
    desc: x coordinate of center-of-action
    default: 0
    bounds: no range checking

-y  type: float
    desc: y coordinate of center-of-action
    default: 0
    bounds: no range checking

EXAMPLES
vwarp -i1 feath.xv -i2 xcoeffs.xv -i3 y coeffs.xv -o warped.xv

warps "feath.xv" according to the coefficients in "xcoeffs.xv" and "ycoeffs.xv".

SEE ALSO
intro(1), verror(3), vgparms(3), vutils(3), lvwarp(3) , lvwarp(3), , lvwarp(3), vrotate(1), vresize(1), vpolyco(1)

RESTRICTIONS
vwarp will not work on images of type BIT or COMPLEX data type. vwarp does not work on explicit location data.

COPYRIGHT
Copyright 1991, University of New Mexico. All rights reserved.