update_fits_wcsinfo

jwst.assign_wcs.update_fits_wcsinfo(datamodel, max_pix_error=0.01, degree=None, npoints=32, crpix=None, projection='TAN', imwcs=None, **kwargs)[source]

Update datamodel.meta.wcsinfo based on a FITS WCS + SIP approximation of a GWCS object. By default, this function will approximate the datamodel’s GWCS object stored in datamodel.meta.wcs but it can also approximate a user-supplied GWCS object when provided via the imwcs parameter.

The default mode in using this attempts to achieve roughly 0.01 pixel accuracy over the entire image.

This function uses the to_fits_sip() to create FITS WCS representations of GWCS objects. Only most important to_fits_sip() parameters are exposed here. Other arguments to to_fits_sip() can be passed via kwargs - see “Other Parameters” section below. Please refer to the documentation of to_fits_sip() for more details.

Warning

This function modifies input data model’s datamodel.meta.wcsinfo members.

Parameters:

  • datamodel (ImageModel) – The input data model for imaging or WFSS mode whose meta.wcsinfo field should be updated from GWCS. By default, datamodel.meta.wcs is used to compute FITS WCS + SIP approximation. When imwcs is not None then computed FITS WCS will be an approximation of the WCS provided through the imwcs parameter.

  • max_pix_error (float, optional) – Maximum allowed error over the domain of the pixel array. This error is the equivalent pixel error that corresponds to the maximum error in the output coordinate resulting from the fit based on a nominal plate scale.

  • degree (int, iterable, None, optional) – Degree of the SIP polynomial. Default value None indicates that all allowed degree values ([1...6]) will be considered and the lowest degree that meets accuracy requerements set by max_pix_error will be returned. Alternatively, degree can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default None but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, degree can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case max_pixel_error is ignored.

  • npoints (int, optional) – The number of points in each dimension to sample the bounding box for use in the SIP fit. Minimum number of points is 3.

  • crpix (list of float, None, optional) – Coordinates (1-based) of the reference point for the new FITS WCS. When not provided, i.e., when set to None (default) the reference pixel already specified in wcsinfo will be re-used. If wcsinfo does not contain crpix information, then the reference pixel will be chosen near the center of the bounding box for axes corresponding to the celestial frame.

  • projection (str, Pix2SkyProjection, optional) – Projection to be used for the created FITS WCS. It can be specified as a string of three characters specifying a FITS projection code from Table 13 in Representations of World Coordinates in FITS (Paper I), Greisen, E. W., and Calabretta, M. R., A & A, 395, 1061-1075, 2002. Alternatively, it can be an instance of one of the astropy’s Pix2Sky_* projection models inherited from Pix2SkyProjection.

  • imwcs (gwcs.WCS, None, optional) –

    Imaging GWCS object for WFSS mode whose FITS WCS approximation should be computed and stored in the datamodel.meta.wcsinfo field. When imwcs is None then WCS from datamodel.meta.wcs will be used.

    Warning

    Used with WFSS modes only. For other modes, supplying a different WCS from datamodel.meta.wcs will result in the GWCS and FITS WCS descriptions to diverge.

  • max_inv_pix_error (float, None, optional) – Maximum allowed inverse error over the domain of the pixel array in pixel units. With the default value of None no inverse is generated.

  • inv_degree (int, iterable, None, optional) – Degree of the SIP polynomial. Default value None indicates that all allowed degree values ([1...6]) will be considered and the lowest degree that meets accuracy requerements set by max_pix_error will be returned. Alternatively, degree can be an iterable containing allowed values for the SIP polynomial degree. This option is similar to default None but it allows caller to restrict the range of allowed SIP degrees used for fitting. Finally, degree can be an integer indicating the exact SIP degree to be fit to the WCS transformation. In this case max_inv_pixel_error is ignored.

  • bounding_box (tuple, None, optional) – A pair of tuples, each consisting of two numbers Represents the range of pixel values in both dimensions ((xmin, xmax), (ymin, ymax))

  • verbose (bool, optional) – Print progress of fits.

Return type:

FITS header with all SIP WCS keywords

Raises:

ValueError – If the WCS is not at least 2D, an exception will be raised. If the specified accuracy (both forward and inverse, both rms and maximum) is not achieved an exception will be raised.

Notes

Use of this requires a judicious choice of required accuracies. Attempts to use higher degrees (~7 or higher) will typically fail due to floating point problems that arise with high powers.

For more details, see to_fits_sip().