
vwarp(1)                     Khoros                      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 rela-
     tionship.  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 follow-
     ing 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 multi-
     plying 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 rec-
     tangular region in the input image (composed of four neigh-
     boring 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 magnify-
     ing 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.

Khoros                    Release: 1.0                          1

