# Functions to Manage WCS Table Extension

These functions provide the basic support for initializing, creating and updating the WCS table extension which serves as the archive of updates made to the WCS information in the image headers.

`stwcs.wcsutil.wcscorr.``archive_wcs_file`(image, wcs_id=None)

  Update WCSCORR table with rows for each SCI extension to record the newly updated WCS keyword values.

`stwcs.wcsutil.wcscorr.``create_wcscorr`(descrip=False, numrows=1, padding=0)

  Return the basic definitions for a WCSCORR table. The dtype definitions for the string columns are set to the maximum allowed so that all new elements will have the same max size which will be automatically truncated to this limit upon updating (if needed).

  The table is initialized with rows corresponding to the OPUS solution for all the ‘SCI’ extensions.

`stwcs.wcsutil.wcscorr.``delete_wcscorr_row`(wcstab, selections=None, rows=None)

  Sets all values in a specified row or set of rows to default values

  This function will essentially erase the specified row from the table without actually removing the row from the table. This avoids the problems with trying to resize the number of rows in the table while preserving the ability to update the table with new rows again without resizing the table.

  Parameters:

  wcstab: object

    PyFITS binTable object for WCSCORR table

  selections: dict

    Dictionary of wcscorr column names and values to be used to select the row or set of rows to erase

  rows: int, list

    If specified, will specify what rows from the table to erase regardless of the value of ‘selections’

`stwcs.wcsutil.wcscorr.``find_wcscorr_row`(wcstab, selections)

  Return an array of indices from the table (NOT HDU) ‘wcstab’ that matches the selections specified by the user.

  The row selection criteria must be specified as a dictionary with column name as key and value(s) representing the valid desired row values. For example, {‘wcs_id’:’OPUS’,’extver’:2}.

`stwcs.wcsutil.wcscorr.``init_wcscorr`(input, force=False)

  This function will initialize the WCSCORR table if it is not already present, and look for WCS keywords with a prefix of ‘O’ as the original OPUS generated WCS as the initial row for the table or use the current WCS keywords as initial row if no ‘O’ prefix keywords are found.

  This function will NOT overwrite any rows already present.

  This function works on all SCI extensions at one time.

`stwcs.wcsutil.wcscorr.``restore_file_from_wcscorr`(image, id='OPUS', wcskey='')

  Copies the values of the WCS from the WCSCORR based on ID specified by user. The default will be to restore the original OPUS-derived values to the Primary WCS. If wcskey is specified, the WCS with that key will be updated instead.

`stwcs.wcsutil.wcscorr.``update_wcscorr`(dest, source=None, extname='SCI', wcs_id=None, active=True)

  Update WCSCORR table with a new row or rows for this extension header. It copies the current set of WCS keywords as a new row of the table based on keyed WCSs as per Paper I Multiple WCS standard).

  Parameters:

  dest : HDUList

    The HDU list whose WCSCORR table should be appended to (the WCSCORR HDU must already exist)

  source : HDUList, optional

    The HDU list containing the extension from which to extract the WCS keywords to add to the WCSCORR table. If None, the dest is also used as the source.

  extname : str, optional

    The extension name from which to take new WCS keywords. If there are multiple extensions with that name, rows are added for each extension version.

  wcs_id : str, optional

    The name of the WCS to add, as in the WCSNAMEa keyword. If unspecified, all the WCSs in the specified extensions are added.

  active: bool, optional

    When True, indicates that the update should reflect an update of the active WCS information, not just appending the WCS to the file as a headerlet

`stwcs.wcsutil.wcscorr.``update_wcscorr_column`(wcstab, column, values, selections=None, rows=None)

  Update the values in ‘column’ with ‘values’ for selected rows

  Parameters:

  wcstab: object

    PyFITS binTable object for WCSCORR table

  column: string

    Name of table column with values that need to be updated

  values: string, int, or list

    Value or set of values to copy into the selected rows for the column

  selections: dict

    Dictionary of wcscorr column names and values to be used to select the row or set of rows to erase

  rows: int, list

    If specified, will specify what rows from the table to erase regardless of the value of ‘selections’

# Functions to Manage Legacy OPUS WCS Keywords in the WCS Table

The previously released versions of `makewcs` provided with `MultiDrizzle` archives the original OPUS generated WCS keywords using header keywords which have a prefix of “O”, such as “OCRPIX1”. In order to avoid overwriting or ignoring these original values, these functions can be used to convert the prefixed OPUS WCS keywords into WCS table entries compatible with the new code.

Strictly to provide complete support for these OPUS keywords, the code will also create, if the user desires, prefix “O” WCS keywords from the alternate WCS FITS conventions OPUS keywords. This would allow images processed using the new code only can then be used with older versions of `MultiDrizzle`, if the user needs such compatibility.

`stwcs.wcsutil.convertwcs.``archive_prefix_OPUS_WCS`(fobj, extname='SCI')

  Identifies WCS keywords which were generated by OPUS and archived using a prefix of ‘O’ for all ‘SCI’ extensions in the file

  Parameters:

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

    Filename or fits object of a file

`stwcs.wcsutil.convertwcs.``create_prefix_OPUS_WCS`(fobj, extname='SCI')

  Creates alternate WCS with a prefix of ‘O’ for OPUS generated WCS values to work with old MultiDrizzle.

  Parameters:

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

    Filename or fits object of a file

  Raises:

  IOError:

    if input FITS object was not opened in ‘update’ mode