WCS

class pywcs.WCS(header=None, fobj=None, key=' ', minerr=0.0, relax=False, naxis=None, keysel=None, colsel=None, fix=True)

WCS objects perform standard WCS transformations, and correct for SIP and Paper IV table-lookup distortions, based on the WCS keywords and supplementary data read from a FITS file.

• header: A string containing the header content, or a PyFITS header object. If header is not provided or None, the object will be initialized to default values.

• fobj: A PyFITS file (hdulist) object. It is needed when header keywords point to a Paper IV Lookup table distortion stored in a different extension.

• key: A string. The name of a particular WCS transform to use. This may be either ' ' or 'A'-'Z' and corresponds to the "a" part of the CTYPEia cards. key may only be provided if header is also provided.

• minerr: A floating-point value. The minimum value a distortion correction must have in order to be applied. If the value of CQERRja is smaller than minerr, the corresponding distortion is not applied.

• relax: Degree of permissiveness:

  • False: Recognize only FITS keywords defined by the published WCS standard.
  • True: Admit all recognized informal extensions of the WCS standard.
  • int: a bit field selecting specific extensions to accept. See Header-reading relaxation constants for details.

• naxis: int or sequence. Extracts specific coordinate axes using sub(). If a header is provided, and naxis is not None, naxis will be passed to sub() in order to select specific axes from the header. See sub() for more details about this parameter.

• keysel: A list of flags used to select the keyword types considered by wcslib. When None, only the standard image header keywords are considered (and the underlying wcspih() C function is called). To use binary table image array or pixel list keywords, keysel must be set.

  Each element in the list should be one of the following strings:

  • ‘image’: Image header keywords
  • ‘binary’: Binary table image array keywords
  • ‘pixel’: Pixel list keywords

  Keywords such as EQUIna or RFRQna that are common to binary table image arrays and pixel lists (including WCSNna and TWCSna) are selected by both ‘binary’ and ‘pixel’.

• colsel: A sequence of table column numbers used to restrict the WCS transformations considered to only those pertaining to the specified columns. If None, there is no restriction.

• fix : When True (default), call fix on the resulting object to fix any non-standard uses in the header.

Warning

pywcs supports arbitrary n dimensions for the core WCS (the transformations handled by WCSLIB). However, the Paper IV lookup table and SIP distortions must be two dimensional. Therefore, if you try to create a WCS object where the core WCS has a different number of dimensions than 2 and that object also contains a Paper IV lookup table or SIP distortion, a ValueError exception will be raised. To avoid this, consider using the naxis kwarg to select two dimensions from the core WCS.

Exceptions:

• MemoryError: Memory allocation failed.
• ValueError: Invalid key.
• KeyError: Key not found in FITS header.
• AssertionError: Lookup table distortion present in the header but fobj not provided.

all_pix2sky(*args, **kwargs)

Transforms pixel coordinates to sky coordinates by doing all of the following in order:

• Detector to image plane correction (optionally)
• SIP distortion correction (optionally)
• Paper IV table-lookup distortion correction (optionally)
• wcslib WCS transformation

Either two or three arguments may be provided.

• 2 arguments: An N x naxis array of x- and y-coordinates, and an origin.
• 3 arguments: 2 one-dimensional arrays of x and y coordinates, and an origin.

Here, origin is the coordinate in the upper left corner of the image. In FITS and Fortran standards, this is 1. In Numpy and C standards this is 0.

Returns the sky coordinates, in degrees. If the input was a single array and origin, a single array is returned, otherwise a tuple of arrays is returned.

An optional keyword argument, ra_dec_order, may be provided, that when True will ensure that sky coordinates are always given and returned in as (ra, dec) pairs, regardless of the order of the axes specified by the in the CTYPE keywords.

For a transformation that is not two-dimensional, the two-argument form must be used.

Note

The order of the axes for the result is determined by the CTYPEia keywords in the FITS header, therefore it may not always be of the form (ra, dec). The lat, lng, lattyp and lngtyp members can be used to determine the order of the axes.

Exceptions:

• MemoryError: Memory allocation failed.
• SingularMatrixError: Linear transformation matrix is singular.
• InconsistentAxisTypesError: Inconsistent or unrecognized coordinate axis types.
• ValueError: Invalid parameter value.
• ValueError: Invalid coordinate transformation parameters.
• ValueError: x- and y-coordinate arrays are not the same size.
• InvalidTransformError: Invalid coordinate transformation parameters.
• InvalidTransformError: Ill-conditioned coordinate transformation parameters.

calcFootprint(header=None, undistort=True)

Calculates the footprint of the image on the sky.

A footprint is defined as the positions of the corners of the image on the sky after all available distortions have been applied.

Returns a (4, 2) array of (x, y) coordinates.

copy()

Return a shallow copy of the object.

Convenience method so user doesn’t have to import the copy stdlib module.

deepcopy()

Return a deep copy of the object.

Convenience method so user doesn’t have to import the copy stdlib module.

det2im(*args, **kwargs)

Convert detector coordinates to image plane coordinates using Paper IV table-lookup distortion correction.

Either two or three arguments may be provided.

• 2 arguments: An N x 2 array of x- and y-coordinates, and an origin.
• 3 arguments: 2 one-dimensional arrays of x and y coordinates, and an origin.

Here, origin is the coordinate in the upper left corner of the image. In FITS and Fortran standards, this is 1. In Numpy and C standards this is 0.

Returns the pixel coordinates. If the input was a single array and origin, a single array is returned, otherwise a tuple of arrays is returned.

Exceptions:

• MemoryError: Memory allocation failed.
• ValueError: Invalid coordinate transformation parameters.

footprint_to_file(filename=None, color='green', width=2)

Writes out a ds9 style regions file. It can be loaded directly by ds9.

• filename: string. Output file name - default is 'footprint.reg'
• color: string. Color to use when plotting the line.
• width: int. Width of the region line.

get_axis_types()

list of dicts

Similar to self.wcsprm.axis_types but provides the information in a more Python-friendly format.

Returns a list of dictionaries, one for each axis, each containing attributes about the type of that axis.

Each dictionary has the following keys:

• ‘coordinate_type’:
  • None: Non-specific coordinate type.
  • ‘stokes’: Stokes coordinate.
  • ‘celestial’: Celestial coordinate (including CUBEFACE).
  • ‘spectral’: Spectral coordinate.
• ‘scale’:
  • ‘linear’: Linear axis.
  • ‘quantized’: Quantized axis (STOKES, CUBEFACE).
  • ‘non-linear celestial’: Non-linear celestial axis.
  • ‘non-linear spectral’: Non-linear spectral axis.
  • ‘logarithmic’: Logarithmic axis.
  • ‘tabular’: Tabular axis.
• ‘group’
  • Group number, e.g. lookup table number
• ‘number’
  • For celestial axes:
    • 0: Longitude coordinate.
    • 1: Latitude coordinate.
    • 2: CUBEFACE number.
  • For lookup tables:
    • the axis number in a multidimensional table.

CTYPEia in "4-3" form with unrecognized algorithm code will generate an error.

get_naxis(header=None)

p4_pix2foc(*args, **kwargs)

Convert pixel coordinates to focal plane coordinates using Paper IV table-lookup distortion correction.

Either two or three arguments may be provided.

• 2 arguments: An N x 2 array of x- and y-coordinates, and an origin.
• 3 arguments: 2 one-dimensional arrays of x and y coordinates, and an origin.

Here, origin is the coordinate in the upper left corner of the image. In FITS and Fortran standards, this is 1. In Numpy and C standards this is 0.

Returns the focal coordinates. If the input was a single array and origin, a single array is returned, otherwise a tuple of arrays is returned.

Exceptions:

• MemoryError: Memory allocation failed.
• ValueError: Invalid coordinate transformation parameters.

pix2foc(*args, **kwargs)

Convert pixel coordinates to focal plane coordinates using the SIP polynomial distortion convention and Paper IV table-lookup distortion correction.

Either two or three arguments may be provided.

• 2 arguments: An N x 2 array of x- and y-coordinates, and an origin.
• 3 arguments: 2 one-dimensional arrays of x and y coordinates, and an origin.

Here, origin is the coordinate in the upper left corner of the image. In FITS and Fortran standards, this is 1. In Numpy and C standards this is 0.

Returns the focal coordinates. If the input was a single array and origin, a single array is returned, otherwise a tuple of arrays is returned.

Exceptions:

• MemoryError: Memory allocation failed.
• ValueError: Invalid coordinate transformation parameters.

printwcs()

Temporary function for internal use.

rotateCD(theta)

sip_foc2pix(*args, **kwargs)

Convert focal plane coordinates to pixel coordinates using the SIP polynomial distortion convention.

Paper IV table lookup distortion correction is not applied, even if that information existed in the FITS file that initialized this WCS object.

Either two or three arguments may be provided.

• 2 arguments: An N x 2 array of x- and y-coordinates, and an origin.
• 3 arguments: 2 one-dimensional arrays of x and y coordinates, and an origin.

Here, origin is the coordinate in the upper left corner of the image. In FITS and Fortran standards, this is 1. In Numpy and C standards this is 0.

Returns the pixel coordinates. If the input was a single array and origin, a single array is returned, otherwise a tuple of arrays is returned.

Exceptions:

• MemoryError: Memory allocation failed.
• ValueError: Invalid coordinate transformation parameters.

sip_pix2foc(*args, **kwargs)

Convert pixel coordinates to focal plane coordinates using the SIP polynomial distortion convention.

Paper IV table lookup distortion correction is not applied, even if that information existed in the FITS file that initialized this WCS object. To correct for that, use pix2foc or p4_pix2foc.

Either two or three arguments may be provided.

• 2 arguments: An N x 2 array of x- and y-coordinates, and an origin.
• 3 arguments: 2 one-dimensional arrays of x and y coordinates, and an origin.

Here, origin is the coordinate in the upper left corner of the image. In FITS and Fortran standards, this is 1. In Numpy and C standards this is 0.

Returns the focal coordinates. If the input was a single array and origin, a single array is returned, otherwise a tuple of arrays is returned.

Exceptions:

• MemoryError: Memory allocation failed.
• ValueError: Invalid coordinate transformation parameters.

sub(axes)

Extracts the coordinate description for a subimage from a WCS object.

The world coordinate system of the subimage must be separable in the sense that the world coordinates at any point in the subimage must depend only on the pixel coordinates of the axes extracted. In practice, this means that the PCi_ja matrix of the original image must not contain non-zero off-diagonal terms that associate any of the subimage axes with any of the non-subimage axes.

sub can also add axes to a wcsprm struct. The new axes will be created using the defaults set by the Wcsprm constructor which produce a simple, unnamed, linear axis with world coordinates equal to the pixel coordinate. These default values can be changed before invoking set.

No checks are performed to verify that the coordinate axes are consistent, that is done by set.

• axes: int or a sequence.
  • If an int, include the first N axes in their original order.
  • If a sequence, may contain a combination of image axis numbers (1-relative) or special axis identifiers (see below). Order is significant; axes[0] is the axis number of the input image that corresponds to the first axis in the subimage, etc. Use an axis number of 0 to create a new axis using the defaults.
  • If 0, [] or None, do a deep copy.

Coordinate axes types may be specified using either strings or special integer constants. The available types are:

• 'longitude' / WCSSUB_LONGITUDE: Celestial longitude
• 'latitude' / WCSSUB_LATITUDE: Celestial latitude
• 'cubeface' / WCSSUB_CUBEFACE: Quadcube CUBEFACE axis
• 'spectral' / WCSSUB_SPECTRAL: Spectral axis
• 'stokes' / WCSSUB_STOKES: Stokes axis
• 'celestial' / WCSSUB_CELESTIAL: An alias for the combination of 'longitude', 'latitude' and 'cubeface'.

Returns a WCS object, which is a deep copy of the original object.

Exceptions:

• MemoryError: Memory allocation failed.
• InvalidSubimageSpecificationError: Invalid subimage specification (no spectral axis).
• NonseparableSubimageCoordinateSystem: Non-separable subimage coordinate system.

Note

Combinations of subimage axes of particular types may be extracted in the same order as they occur in the input image by combining the integer constants with the ‘binary or’ (|) operator. For example:

wcs.sub([WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_SPECTRAL])

would extract the longitude, latitude, and spectral axes in the same order as the input image. If one of each were present, the resulting object would have three dimensions.

For convenience, WCSSUB_CELESTIAL is defined as the combination WCSSUB_LONGITUDE | WCSSUB_LATITUDE | WCSSUB_CUBEFACE.

The codes may also be negated to extract all but the types specified, for example:

wcs.sub([
  WCSSUB_LONGITUDE,
  WCSSUB_LATITUDE,
  WCSSUB_CUBEFACE,
  -(WCSSUB_SPECTRAL | WCSSUB_STOKES)])

The last of these specifies all axis types other than spectral or Stokes. Extraction is done in the order specified by axes, i.e. a longitude axis (if present) would be extracted first (via axes[0]) and not subsequently (via axes[3]). Likewise for the latitude and cubeface axes in this example.

The number of dimensions in the returned object may be less than or greater than the length of axes. However, it will never exceed the number of axes in the input image.

to_fits(relax=False, wkey=None)

Generate a pyfits.HDUList object with all of the information stored in this object. This should be logically identical to the input FITS file, but it will be normalized in a number of ways.

See WCS.to_header for some warnings about the output produced.

• relax: Degree of permissiveness:
  • False: Recognize only FITS keywords defined by the published WCS standard.
  • True: Admit all recognized informal extensions of the WCS standard.
  • int: a bit field selecting specific extensions to write. See Header-writing relaxation constants for details.

Returns a pyfits.HDUList object.

to_header(relax=False, wkey=None)

Generate a pyfits.Header object with the basic WCS and SIP information stored in this object. This should be logically identical to the input FITS file, but it will be normalized in a number of ways.

Warning

This function does not write out Paper IV distortion information, since that requires multiple FITS header data units. To get a full representation of everything in this object, use to_fits.

The output header will almost certainly differ from the input in a number of respects:

1. The output header only contains WCS-related keywords. In particular, it does not contain syntactically-required keywords such as SIMPLE, NAXIS, BITPIX, or END.
2. Deprecated (e.g. CROTAn) or non-standard usage will be translated to standard (this is partially dependent on whether fix was applied).
3. Quantities will be converted to the units used internally, basically SI with the addition of degrees.
4. Floating-point quantities may be given to a different decimal precision.
5. Elements of the PCi_j matrix will be written if and only if they differ from the unit matrix. Thus, if the matrix is unity then no elements will be written.
6. Additional keywords such as WCSAXES, CUNITia, LONPOLEa and LATPOLEa may appear.
7. The original keycomments will be lost, although to_header tries hard to write meaningful comments.
8. Keyword order may be changed.

• relax: Degree of permissiveness:
  • False: Recognize only FITS keywords defined by the published WCS standard.
  • True: Admit all recognized informal extensions of the WCS standard.
  • int: a bit field selecting specific extensions to write. See Header-writing relaxation constants for details.
• wkey: A string. The name of a particular WCS transform to use. This may be either ' ' or 'A'-'Z' and corresponds to the "a" part of the CTYPEia cards.

Returns a pyfits.Header object.

to_header_string(relax=False)

Identical to to_header, but returns a string containing the header cards.

wcs_pix2sky(*args, **kwargs)

Transforms pixel coordinates to sky coordinates by doing only the basic wcslib transformation. No SIP or Paper IV table lookup distortion correction is applied. To perform distortion correction, see all_pix2sky, sip_pix2foc, p4_pix2foc, or pix2foc.

Either two or three arguments may be provided.

• 2 arguments: An N x naxis array of x- and y-coordinates, and an origin.
• 3 arguments: 2 one-dimensional arrays of x and y coordinates, and an origin.

Here, origin is the coordinate in the upper left corner of the image. In FITS and Fortran standards, this is 1. In Numpy and C standards this is 0.

Returns the sky coordinates, in degrees.. If the input was a single array and origin, a single array is returned, otherwise a tuple of arrays is returned.

An optional keyword argument, ra_dec_order, may be provided, that when True will ensure that sky coordinates are always given and returned in as (ra, dec) pairs, regardless of the order of the axes specified by the in the CTYPE keywords.

For a transformation that is not two-dimensional, the two-argument form must be used.

Note

The order of the axes for the result is determined by the CTYPEia keywords in the FITS header, therefore it may not always be of the form (ra, dec). The lat, lng, lattyp and lngtyp members can be used to determine the order of the axes.

Exceptions:

• MemoryError: Memory allocation failed.
• SingularMatrixError: Linear transformation matrix is singular.
• InconsistentAxisTypesError: Inconsistent or unrecognized coordinate axis types.
• ValueError: Invalid parameter value.
• ValueError: Invalid coordinate transformation parameters.
• ValueError: x- and y-coordinate arrays are not the same size.
• InvalidTransformError: Invalid coordinate transformation parameters.
• InvalidTransformError: Ill-conditioned coordinate transformation parameters.

wcs_sky2pix(*args, **kwargs)

Transforms sky coordinates to pixel coordinates, using only the basic wcslib WCS transformation. No SIP or Paper IV table lookup distortion is applied.

Either two or three arguments may be provided.

• 2 arguments: An N x naxis array of x- and y-coordinates, and an origin.
• 3 arguments: 2 one-dimensional arrays of x and y coordinates, and an origin.

Here, origin is the coordinate in the upper left corner of the image. In FITS and Fortran standards, this is 1. In Numpy and C standards this is 0.

Returns the pixel coordinates. If the input was a single array and origin, a single array is returned, otherwise a tuple of arrays is returned.

An optional keyword argument, ra_dec_order, may be provided, that when True will ensure that sky coordinates are always given and returned in as (ra, dec) pairs, regardless of the order of the axes specified by the in the CTYPE keywords.

For a transformation that is not two-dimensional, the two-argument form must be used.

Note

The order of the axes for the input sky array is determined by the CTYPEia keywords in the FITS header, therefore it may not always be of the form (ra, dec). The lat, lng, lattyp and lngtyp members can be used to determine the order of the axes.

Exceptions:

• MemoryError: Memory allocation failed.
• SingularMatrixError: Linear transformation matrix is singular.
• InconsistentAxisTypesError: Inconsistent or unrecognized coordinate axis types.
• ValueError: Invalid parameter value.
• InvalidTransformError: Invalid coordinate transformation parameters.
• InvalidTransformError: Ill-conditioned coordinate transformation parameters.

cpdis1

DistortionLookupTable

The pre-linear transformation distortion lookup table, CPDIS1.

cpdis2

DistortionLookupTable

The pre-linear transformation distortion lookup table, CPDIS2.

det2im1

A DistortionLookupTable object for detector to image plane correction in the x-axis. double

The native latitude of the celestial pole, LATPOLEa (deg).

det2im2

A DistortionLookupTable object for detector to image plane correction in the y-axis. The name of the unit being converted to.

This value always uses standard unit names, even if the UnitConverter was initialized with a non-standard unit name.

sip

Get/set the Sip object for performing SIP distortion correction.

wcs

A Wcsprm object to perform the basic wcslib WCS tranformation.

functions

pywcs.find_all_wcs(header, relax=False, keysel=None)

Find all the WCS transformations in the given header.

• header: A string or PyFITS header object.

• relax: Degree of permissiveness:

  • False: Recognize only FITS keywords defined by the published WCS standard.
  • True: Admit all recognized informal extensions of the WCS standard.
  • int: a bit field selecting specific extensions to accept. See Header-reading relaxation constants for details.

• keysel: A list of flags used to select the keyword types considered by wcslib. When None, only the standard image header keywords are considered (and the underlying wcspih() C function is called). To use binary table image array or pixel list keywords, keysel must be set.

  Each element in the list should be one of the following strings:

  • ‘image’: Image header keywords
  • ‘binary’: Binary table image array keywords
  • ‘pixel’: Pixel list keywords

  Keywords such as EQUIna or RFRQna that are common to binary table image arrays and pixel lists (including WCSNna and TWCSna) are selected by both ‘binary’ and ‘pixel’.

Returns a list of WCS objects.