# WCS Utilities

These functions read and interpret the WCS information from input images and create the output WCS objects based on STWCS routines.

Authors: | Warren Hack
License: | http://www.stsci.edu/resources/software_hardware/pyraf/LICENSE

class `drizzlepac.wcs_functions.``IdentityMap`(input, output)
  `forward`(pixx, pixy)

class `drizzlepac.wcs_functions.``LinearMap`(xsh=0.0, ysh=0.0, rot=0.0, scale=1.0)
  `forward`(pixx, pixy)

class `drizzlepac.wcs_functions.``WCSMap`(input, output, origin=1)

  Sample class to demonstrate how to define a coordinate transformation

  `backward`(pixx, pixy)

    Transform pixx,pixy positions from the output frame back onto their original positions in the input frame.

  `checkWCS`(obj, name)
  `forward`(pixx, pixy)

    Transform the input pixx,pixy positions in the input frame to pixel positions in the output frame.

    This method gets passed to the drizzle algorithm.

  `get_pix_ratio`()

    Return the ratio of plate scales between the input and output WCS. This is used to properly distribute the flux in each pixel in ‘tdriz’.

  `rd2xy`(wcs, ra, dec)

    Transform input sky positions into pixel positions in the WCS provided.

  `xy2rd`(wcs, pixx, pixy)

    Transform input pixel positions into sky positions in the WCS provided.

`drizzlepac.wcs_functions.``apply_fitlin`(data, P, Q)

`drizzlepac.wcs_functions.``build_hstwcs`(crval1, crval2, crpix1, crpix2, naxis1, naxis2, pscale, orientat)

  Create an HSTWCS object for a default instrument without distortion based on user provided parameter values.

`drizzlepac.wcs_functions.``build_pixel_transform`(chip, output_wcs)

`drizzlepac.wcs_functions.``calcNewEdges`(wcs, shape)

  This method will compute sky coordinates for all the pixels around the edge of an image AFTER applying the geometry model.

  Parameters:

  wcs : obj

  > HSTWCS object for image

  shape : tuple

  > numpy shape tuple for size of image

  Returns:

  border : arr

  > array which contains the new positions for all pixels around the border of the edges in alpha,dec

`drizzlepac.wcs_functions.``computeEdgesCenter`(edges)

`drizzlepac.wcs_functions.``convertWCS`(inwcs, drizwcs)

  Copy WCSObject WCS into Drizzle compatible array.

`drizzlepac.wcs_functions.``createWCSObject`(output, default_wcs, imageObjectList)

  Converts a PyWCS WCS object into a WCSObject(baseImageObject) instance.

`drizzlepac.wcs_functions.``create_CD`(orient, scale, cx=None, cy=None)

  Create a (un?)distorted CD matrix from the basic inputs

  The ‘cx’ and ‘cy’ parameters, if given, provide the X and Y coefficients of the distortion as returned by reading the IDCTAB. Only the first 2 elements are used and should correspond to the ‘OC[X/Y]10’ and ‘OC[X/Y]11’ terms in that order as read from the expanded SIP headers.

  The units of ‘scale’ should be ‘arcseconds/pixel’ of the reference pixel. The value of ‘orient’ should be the absolute orientation on the sky of the reference pixel.

`drizzlepac.wcs_functions.``ddtohms`(xsky, ysky, verbose=False, precision=6)

  Convert sky position(s) from decimal degrees to HMS format.

`drizzlepac.wcs_functions.``fitlin`(imgarr, refarr)

  Compute the least-squares fit between two arrays. A Python translation of ‘FITLIN’ from ‘drutil.f’ (Drizzle V2.9).

`drizzlepac.wcs_functions.``fitlin_clipped`(xy, uv, verbose=False, mode='rscale', nclip=3, reject=3)

  Perform a clipped fit based on the number of iterations and rejection limit (in sigma) specified by the user. This will more closely replicate the results obtained by ‘geomap’ using ‘maxiter’ and ‘reject’ parameters.

`drizzlepac.wcs_functions.``fitlin_rscale`(xy, uv, verbose=False)

  Performs a linear, orthogonal fit between matched lists of positions ‘xy’ (input) and ‘uv’ (output).

  Output: (same as for fit_arrays_general)

`drizzlepac.wcs_functions.``get_hstwcs`(filename, hdulist, extnum)

  Return the HSTWCS object for a given chip.

`drizzlepac.wcs_functions.``get_pix_ratio_from_WCS`(input, output)

  [Functional form of .get_pix_ratio() method of WCSMap]

`drizzlepac.wcs_functions.``make_outputwcs`(imageObjectList, output, configObj=None, perfect=False)

  Computes the full output WCS based on the set of input imageObjects provided as input, along with the pre-determined output name from process_input. The user specified output parameters are then used to modify the default WCS to produce the final desired output frame. The input imageObjectList has the outputValues dictionary updated with the information from the computed output WCS. It then returns this WCS as a WCSObject(imageObject) instance.

`drizzlepac.wcs_functions.``make_perfect_cd`(wcs)

  Create a perfect (square, orthogonal, undistorted) CD matrix from the input WCS.

`drizzlepac.wcs_functions.``mergeWCS`(default_wcs, user_pars)

  Merges the user specified WCS values given as dictionary derived from the input configObj object with the output PyWCS object computed using distortion.output_wcs().

  The user_pars dictionary needs to have the following set of keys:

      user_pars = {'ra':None,'dec':None,'scale':None,'rot':None,
                   'outnx':None,'outny':None,'crpix1':None,'crpix2':None}

`drizzlepac.wcs_functions.``readAltWCS`(fobj, ext, wcskey=' ', verbose=False)

  Reads in alternate primary WCS from specified extension.

  Parameters:

  fobj : str, `astropy.io.fits.HDUList`

  > fits filename or fits file object containing alternate/primary WCS(s) to be converted

  wcskey : str

  > [” ”,A-Z] alternate/primary WCS key that will be replaced by the new key

  ext : int

  > fits extension number

  Returns

  ——-

  hdr: fits.Header

  > header object with ONLY the keywords for specified alternate WCS

`drizzlepac.wcs_functions.``removeAllAltWCS`(hdulist, extlist)

  Removes all alternate WCS solutions from the header

`drizzlepac.wcs_functions.``restoreDefaultWCS`(imageObjectList, output_wcs)

  Restore WCS information to default values, and update imageObject accordingly.

`drizzlepac.wcs_functions.``updateImageWCS`(imageObjectList, output_wcs)

`drizzlepac.wcs_functions.``updateWCS`(drizwcs, inwcs)

  Copy output WCS array from Drizzle into WCSObject.

`drizzlepac.wcs_functions.``update_linCD`(cdmat, delta_rot=0.0, delta_scale=1.0, cx=[0.0, 1.0], cy=[1.0, 0.0])

  Modify an existing linear CD matrix with rotation and/or scale changes and return a new CD matrix. If ‘cx’ and ‘cy’ are specified, it will return a distorted CD matrix.

  Only those terms which are varying need to be specified on input.

`drizzlepac.wcs_functions.``wcsfit`(img_wcs, ref_wcs)

  Perform a linear fit between 2 WCS for shift, rotation and scale. Based on the WCSLIN function from ‘drutil.f’(Drizzle V2.9) and modified to allow for differences in reference positions assumed by PyDrizzle’s distortion model and the coeffs used by ‘drizzle’.

  Parameters:

  img : obj

  > ObsGeometry instance for input image

  ref_wcs : obj

  > Undistorted WCSObject instance for output frame