Pixel Area Map (PAM) utilities

A module that provides functions for computing Pixel Area Maps (PAM) based on polynomial distortion model contained in a FITS WCS. Tabular distortions NPOL and DET2IM used to describe HST/ACS distortions are ignored.

Authors:

Mihai Cara

License:

LICENSE

stsci.skypac.pamutils.pam_from_file(image, ext, output_pam, ignore_vacorr=False, normalize_at=None)

Generate a Pixel Area Map (PAM) file from the FITS WCS contained in an image extension of a calibrated HST image file specified by image.

Note

PAM computation is performed using the distortion model defined in the WCS and described through Simple Image Polynomials (SIP). Non-polynomial distortions are ignored!

Parameters:

image: str

File name of a FITS image that will provide a FITS WCS (stwcs.wcsutils.HSTWCS or astropy.wcs.WCS).

ext: int, str, tuple of (str, int)

Extension specification. May be an integer extension number, a string extension name, or a tuple of extension name and extension version.

output_pam: str

Output file name to which PAM will be written.

Warning

If the output file already exists, it will be overwritten without warnings.

ignore_vacorr: bool, optional

When set to True, PAM will be generated as if vellocity aberration has not applied to the WCS.

Warning

This function does not know whether velocity aberration (VA) correction has been applied to the WCS or not. It is user’s responsibility to check the appropriateness of settung this parameter to True. Setting ignore_vacorr to True when WCS was not VA-corrected will result in larger errors in computed PAM. Default value is highly recommended!

normalize_at: tuple of int, optional

Indicates whether to normalize computed PAM to 1 at the provided zero-based pixel position. By default, PAM is computed relative to (or, in units of) the idcscale (for HST instruments) value when present or to the pixel scale at CRPIX when the wcs object does not have an idcscale property. Default setting should produce results analogous to the drizzle/blot method.

Note

HST/WFC3 PAM historically are normalized to 1 at specific pixel positions. See http://www.stsci.edu/hst/wfc3/pam/pixel_area_maps for further details.

stsci.skypac.pamutils.pam_from_wcs(wcs, shape=None, ignore_vacorr=False, normalize_at=None)

Generate a Pixel Area Map (PAM) file from a FITS WCS.

Note

PAM computation is performed using the distortion model defined in the WCS and described through Simple Image Polynomials (SIP). Non-polynomial distortions are ignored!

Parameters:

wcs: stwcs.wcsutils.HSTWCS, astropy.wcs.WCS

An WCS object to be used for generating PAM file.

shape: tuple of two int, None, optional

Shape of the output image (ny, nx). If se to default None, this function will try to deduce the shape of the output image from the value of array_shape attribute of the input wcs object.

ignore_vacorr: bool, optional

When set to True, PAM will be generated as if vellocity aberration has not applied to the WCS.

Warning

This function does not know whether velocity aberration (VA) correction has been applied to the WCS or not. It is user’s responsibility to check the appropriateness of settung this parameter to True. Setting ignore_vacorr to True when WCS was not VA-corrected will result in larger errors in computed PAM. Default value is highly recommended!

normalize_at: tuple of int, optional

Indicates whether to normalize computed PAM to 1 at the provided zero-based pixel position. By default, PAM is computed relative to (or, in units of) the idcscale (for HST instruments) value when present or to the pixel scale at CRPIX when the wcs object does not have an idcscale property. Default setting should produce results analogous to the drizzle/blot method.

Note

HST/WFC3 PAM historically are normalized to 1 at specific pixel positions. See http://www.stsci.edu/hst/wfc3/pam/pixel_area_maps for further details.

Returns:

pam: numpy.ndarray

A 2D numpy.ndarray containing PAM.

Raises:

ValueError

When both shape and wcs.array_shape attribute are None.