Skip to main content
`Ctrl`+`K`

# Legacy Interface

## astropy.wcs API

The `Low Level API` or `Legacy Interface` is the original `astropy.wcs` API. It supports three types of transforms:

- Core WCS, as defined in the FITS WCS standard, based on Mark Calabretta’s wcslib. (Also includes `TPV` and `TPD` distortion, but not `SIP`).

- Simple Imaging Polynomial (SIP) convention. (See note about SIP in headers.)

- Table lookup distortions as defined in the FITS WCS distortion paper.

Each of these transformations can be used independently or together in a standard pipeline. All methods support scalar and array inputs. Note, that all methods require an additional positional argument which is the `origin` of the inputs. It has two possible values - `0` - for zero-based coordinates like numpy arrays or `1` - for 1-based coordinates, like the FITS standard, or those coming from ds9.

The basic workflow is to create a WCS object calling the WCS constructor with an `Header` and/or `HDUList` object and calling one of the methods below:

    >>> from astropy import wcs
    >>> from astropy.io import fits
    >>> from astropy.utils.data import get_pkg_data_filename
    >>> fn = get_pkg_data_filename('data/j94f05bgq_flt.fits', package='astropy.wcs.tests')
    >>> f = fits.open(fn)
    >>> wcsobj = wcs.WCS(f[1].header)
    >>> f.close()

Optionally, if the FITS file uses any deprecated or non-standard features, you may need to call one of the `fix` methods on the object.

Use one of the following transformation methods.

1. Between pixels and world coordinates using all distortions:

> > - `all_pix2world`: Perform all three transformations in series (core WCS, SIP and table lookup distortions) from pixel to world coordinates. Use this one if you’re not sure which to use.

> >       >>> lon, lat = wcsobj.all_pix2world(30, 40, 0)
> >       >>> print(lon, lat)
> >       5.528442425094046 -72.05207808966726

> > - `all_world2pix`: Perform all three

> >     transformations (core WCS, SIP and table lookup distortions) from world to pixel coordinates, using an iterative method if necessary.

> >         >>> x, y = wcsobj.all_world2pix(lon, lat, 0)
> >         >>> print(x, y) #
> >         30.00000214673885 39.999999958235094

> 2. Performing SIP transformations only:

>    > - `sip_pix2foc`: Convert from pixel to

>    >     focal plane coordinates using the SIP polynomial coefficients.

>    >         >>> xsip, ysip = wcsobj.sip_pix2foc(30, 40, 0)
>    >         >>> print(xsip, ysip)
>    >         -1985.8600487630586 -984.4223711273145

>    > - `sip_foc2pix`: Convert from focal

>    >     plane to pixel coordinates using the SIP polynomial coefficients. Note that this method only works if the inverse SIP distortion is specified in the header.

> 3. Performing distortion paper transformations only:

>    > - `p4_pix2foc`: Convert from pixel to

>    >     focal plane coordinates using the table lookup distortion method described in the FITS WCS distortion paper.

>    > - `det2im`: Convert from detector

>    >     coordinates to image coordinates. Commonly used for narrow column correction.

## Core wcslib API

The core wcslib API supports the FITS WCS standard defined in WCS papers, I, II, III, IV. Note that distortions are not applied if the functions in the core library are used.

1. From pixels to world coordinates:

   > - `wcs_pix2world`: Perform just the core WCS

   >     transformation from pixel to world coordinates.

   >         >>> lon, lat = wcsobj.wcs_pix2world(30, 40, 0)
   >         >>> print(lon, lat)
   >         5.527103615238458 -72.0522441352217

2. From world to pixel coordinates:

   > - `wcs_world2pix`: Perform the core WCS transformation

   >     from world to pixel coordinates.

   >         >>> x, y = wcsobj.wcs_world2pix(lon, lat, 0)
   >         >>> print(x, y)
   >         30.000000000223267 40.0000000003696