User Interface: altwcs

The functions in this module manage alternate WCS’s in a header.

stwcs.wcsutil.altwcs.archive_wcs(fname, ext, wcskey=None, wcsname=None, mode=<ArchiveMode.NO_CONFLICT: 0>)

Copy the primary WCS to the header as an alternate WCS with the specified wcskey and name wcsname. It loops over all extensions in ‘ext’.

Parameters:

  • fname (string or astropy.io.fits.HDUList) – File name or a astropy.io.fits.HDUList whose primary WCS need to be archived.

  • ext (int, tuple, str, or list of integers or tuples (e.g.('sci',1))) –

    Specifies FITS extensions whose primary WCS should be archived.

    If a string is provided, it should specify the EXTNAME of extensions with WCSs to be archived

  • wcskey ({'A'-'Z'}, None, optional) – When wcskey is None, and wcsname is not None and an alternate WCS exist with the same name as wcsname, the key of this alernate WCS will be used for wcskey. If wcsname is unique, the next available key will be used. If wcskey is a letter 'A'-'Z', the primary WCS will be archived to the indicated key. If an alternate WCS with the specified key already exist an exception will be raisen unless mode includes either flag ArchiveMode.OVERWRITE_KEY or ArchiveMode.QUIET_ABORT.

  • wcsname (str, None, optional) –

    Name of alternate WCS description. If None, the WCS name will be initially set to the name of the primary WCS if available. If primary WCS does not have 'WCSNAME' set and provided wcskey is not None and a WCS with this key already exists in the header, the name of this alternate WCS will be used. I this alternate WCS does not have 'WCSNAME' set and provided, a default WCS name will be used.

    Note

    An exception will be raisen if an alternate WCS with provided name already exists in image’s headers unless mode includes ArchiveMode.AUTO_RENAME flag in which case wcsname will be automatically adjusted to be unique.

  • mode (int, optional) –

    An integer mask containing one or more flags from ArchiveMode:

    • NO_CONFLICT: Archive only when provided WCS key or name do not conflict with existing alternate WCS or when existing alternate WCS is identical to the primary WCS being archived.

    • AUTO_RENAME: Rename primary WCS if same name is already used by an alternate WCS (in order to keep alternate WCS names unique).

    • OVERWRITE_KEY: Overwrite an existing alternate WCS with the same key as wcskey.

    • QUIET_ABORT: Stop archiving and quit if conflicts exists without raising exceptions.

Returns:

wcs_id – Returns effective WCS key and name used for the archived WCS. If archival failed due to conflicts, and mode was set to ArchiveMode.QUIET_ABORT a tuple of (None, None) will be returned.

Return type:

tuple (str or None, str or None)

stwcs.wcsutil.altwcs.restoreWCS(f, ext, wcskey=' ', wcsname=' ')

Copy a WCS with key “WCSKEY” to the primary WCS

Reads in a WCS defined with wcskey and saves it as the primary WCS. Goes sequentially through the list of extensions in ext. Alternatively uses ‘fromext’ and ‘toext’.

Parameters:

  • f (str or astropy.io.fits.HDUList) – file name or a file object

  • ext (int, tuple, str, or list of integers or tuples (e.g.('sci',1))) – fits extensions to work with If a string is provided, it should specify the EXTNAME of extensions with WCSs to be archived

  • wcskey (str) – “A”-“Z” - Used for one of 26 alternate WCS definitions. or “ “ - find a key from WCSNAMe value

  • wcsname (str) – (optional) if given and wcskey is “ “, will try to restore by WCSNAME value

See also

archive_wcs, restore_from_to

stwcs.wcsutil.altwcs.deleteWCS(fname, ext, wcskey=' ', wcsname=' ')

Delete an alternate WCS defined with wcskey. If wcskey is “ “ try to get a key from WCSNAME.

Parameters:

  • fname (str or a astropy.io.fits.HDUList)

  • ext (int, tuple, str, or list of integers or tuples (e.g.('sci',1))) – fits extensions to work with If a string is provided, it should specify the EXTNAME of extensions with WCSs to be archived

  • wcskey (str) – one of ‘A’-‘Z’ or “ “

  • wcsname (str) – Name of alternate WCS description

stwcs.wcsutil.altwcs.wcsnames(fobj, ext=None, include_primary=True)

Returns a dictionary of wcskey: WCSNAME pairs

Parameters:
stwcs.wcsutil.altwcs.wcskeys(fobj, ext=None)

Returns a list of characters used in the header for alternate WCS description with WCSNAME keyword

Parameters:
stwcs.wcsutil.altwcs.available_wcskeys(fobj, ext=None)

Returns a list of characters which are not used in the header with WCSNAME keyword. Any of them can be used to save a new WCS.

Parameters:
stwcs.wcsutil.altwcs.next_wcskey(fobj, ext=None)

Returns next available character to be used for an alternate WCS

Parameters:
stwcs.wcsutil.altwcs.getKeyFromName(header, wcsname)

If WCSNAME is found in header, return its key, else return None. This is used to update an alternate WCS repeatedly and not generate new keys every time.

Parameters: