**pixtopix** transforms pixel positions given as X,Y values into
positions in another WCS frame based on the WCS information and any
recognized distortion keywords from the input image header.

Examples
--------
This task can be run from either the TEAL GUI or from the Python
command-line. These examples illustrate the syntax that can be used
to run the task in a couple of common modes.

1. Run the task using the TEAL GUI under PyRAF:

    >>> import drizzlepac
    >>> epar pixtopix

2. Convert the position 256,256 from 'input_flt.fits[sci,1]'
     into a position on the output image 'output_drz.fits[sci,1]' using:

            >>> from drizzlepac import pixtopix
            >>> outx,outy = pixtopix.tran("input_file_flt.fits[sci,1]",
                        "output_drz.fits[sci,1],"forward", 256,256)

3. The set of X,Y positions from 'output_drz.fits[sci,1]' stored as
      the 3rd and 4th columns from the ASCII file 'xy_sci1.dat'
      will be transformed into pixel positions from 'input_flt.fits[sci,1]'
      and written out to 'xy_flt1.dat' using::

            >>> from drizzlepac import pixtopix
            >>> x,y = pixtopix.tran("input_flt.fits[sci,1]",
                     "output_drz.fits[sci,1]", "backward",
                     coords='xy_sci1.dat', colnames=['c3','c4'],
                     output="xy_flt1.dat")


Parameters
----------
  inimage : str
    full filename with path of input image, an extension name ['sci',1]
    should be provided if input is a multi-extension FITS file
  outimage : str, optional
    full filename with path of output image, an extension name ['sci',1]
    should be provided if output is a multi-extension FITS file.  If no image gets
        specified, the input image will be used to generate a default output
        WCS using stwcs.distortion.util.output_wcs().
  direction : str
    Direction of transform (forward or backward). The 'forward' transform
    takes the pixel positions (assumed to be from the 'input' image) and
    determines their position in the 'output' image. The 'backward'
    transform converts the pixel positions (assumed to be from the
    'output' image) into pixel positions in the 'input' image.

Optional Parameters
-------------------
  x : float, optional
    X position from image
  y : float, optional
    Y position from image
  coords : str, optional
    full filename with path of file with starting x,y coordinates
  colnames : str, optional
    comma separated list of column names from 'coords' files
    containing x,y coordinates, respectively. Will default to
    first two columns if None are specified. Column names for ASCII
    files will use 'c1','c2',... convention.
  separator : str, optional
    non-blank separator used as the column delimiter in the coords file
  precision : int, optional
    Number of floating-point digits in output values
  output : str, optional
    Name of output file with results, if desired
  verbose : bool
    Print out full list of transformation results (default: False)

RETURNS
-------
  outx : float
    X position of transformed pixel. If more than 1 input value, then it
    will be a numpy array.
  outy : float
    Y position of transformed pixel. If more than 1 input value, then it
    will be a numpy array.

Notes
-----
This task performs a full distortion-correction coordinate transformation
based on all WCS keywords and any recognized distortion keywords from the
input image header.  The transformation recognizes the conventions for
describing distortion implemented as part of the SIP and Paper IV conventions
used with AstroDrizzle.  Input images can be updated to use these conventions
through the use of the 'updatewcs' module the STWCS package.


See Also
--------
stwcs
