Astrometry Database Interface

This module provides an interface for accessing a database which contains updated WCS solutions for many images in the HST archive. The exact set of images with new solutions in this database will change over time, with the initial release containing updates only for ACS and WFC3 direct images. This database will be designed to provide multiple WCS solutions for each exposure depending on what astrometric frame was used to define the new WCS solution; for example, an image may be matched to Pan-STARRS sources in one solution and to GAIA sources in another solution.

Each new WCS solution will be appended to the exposure by this module as a headerlet extension, taking advantage of the headerlet definition provided by the STWCS package, found in Headerlet documentation. The headerlet library allows a user to manage all appended solutions and determine which one gets used by the exposure at anytime, since only 1 WCS can be used at a time.


This interface defines an object that provides the services for updating an exposure with new WCS solutions. Only 2 calls are typically necessary to update any exposure or set of exposures.

0. Import the package

>>> from stwcs.updatewcs import astrometry_utils as stwcsau

1. Establish a working connection with the database

>>> db = stwcsau.AstrometryDB()

2. For each exposure, query the database and update with any new WCS solutions

>>> db.updateObs(filename)

The environment variables used by this module can be defined by the user to change what database is being accessed, whether to raise exceptions instead of warnings when problems arise in connecting to the database or otherwise updating an exposure, or to completely turn on/off use of this module. These allow external code, such as updatewcs (see updatewcs), to include this code and control it as necessary.


Interface for Astrometry database service.

This module contains interface functions for the AstrometryDB Restful service based on interfaces/code provided by B. McLean 11-Oct-2017.

The code checks for the existence of environmental variables to help control the operation of this interface; namely,

RAISE_PIPELINE_ERRORS - boolean to specify whether to raise exceptions

during processing or simply log errors and quit gracefully. If not set, default behavior will be to log errors and quit gracefully.

ASTROMETRY_SERVICE_URL - URL pointing to user-specified web service that

will provide updated astrometry solutions for observations being processed. This will replace the built-in URL included in the base class. This value will also be replaced by any URL provided by the user as an input parameter url.

ASTROMETRY_STEP_CONTROL - String specifying whether or not to perform the

astrometry update processing at all. Valid Values: “ON”, “On”, “on”, “OFF”, “Off”, “off” If not set, default value is “ON”.

GSSS_WEBSERVICES_URL - URL point to user-specified web service which provides

information on the guide stars used for taking HST observations. This value will replace the default URL included in this module as the gsss_url variable.

class stwcs.updatewcs.astrometry_utils.AstrometryDB(url=None, raise_errors=None, perform_step=True, write_log=False)

Bases: object

Base class for astrometry database interface.


Compute and apply a new a priori WCS based on offsets from astrometry database.


obsname (str) – Full filename or object for the observation to be corrected


wcsname – Value of WCSNAME keyword for this new WCS

Return type:



Find whether there are any entries in the AstrometryDB for the observation with observationID.


observationID (str) – base rootname for observation to be updated (eg., iab001a1q)


entry – Database entry for this observation, if found. It will return None if there was an error in accessing the database and self.raise_errors was not set to True.

Return type:



Get solutions for observation from AstrometryDB.


observationID (str) – base rootname for observation to be updated (eg., iab001a1q)


  • headerlets (dict) – Dictionary containing all solutions found for exposure in the form of headerlets labelled by the name given to the solution in the database.

  • best_solution_id (str) – WCSNAME of the WCS solution flagged as ‘best’ in the astrometry database for the observation. The ‘best’ solution should be the one that aligns the observation as close to the GAIA frame as possible.


Test availability of astrometryDB web-service.

updateObs(obsname, all_wcs=False, remove_duplicates=True)

Update observation with any available solutions.

  • obsname (str) – Filename for observation to be updated

  • all_wcs (bool) – If True, all solutions from the Astrometry database are appended to the input file as separate FITS extensions. If False, only those solutions based on the same IDCTAB will be appended.

  • remove_duplicates (bool) – If True, any headerlet extensions with the same HDRNAME are found, the copies will be deleted until only the first version added remains.

stwcs.updatewcs.astrometry_utils.apply_astrometric_updates(obsnames, **pars)

Apply new astrometric solutions to observation.

Functional stand-alone interface for applying new astrometric solutions found in the astrometry dB to the given observation(s).

  • obsnames (str, list) – Filename or list of filenames of observation(s) to be updated

  • url (str, optional) – URL of astrometry database web-interface to use. If None (default), it will use built-in URL for STScI web-interface

  • raise_errors (bool, optional) – Specify whether or not to raise Exceptions and stop processing when an error in either accessing the database, retrieving a solution from the database or applying the new solution to the observation. If None, it will look to see whether the environmental variable RAISE_PIPELINE_ERRORS was set, otherwise, it will default to ‘False’.


stwcs.__version__ = '1.7.3a1.dev24+gd0ba69c.d20240416'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.