World Coordinate System (
World Coordinate Systems (WCSs) describe the geometric transformations between one set of coordinates and another. A common application is to map the pixels in an image onto the celestial sphere. Another common application is to map pixels to wavelength in a spectrum.
astropy.wcs contains utilities for managing World Coordinate System
(WCS) transformations defined in several elaborate FITS WCS standard conventions.
These transformations work both forward (from pixel to world) and backward
(from world to pixel).
For historical reasons and to support legacy software,
two separate application interfaces. The
High-Level API should be used by
most applications. It abstracts out the underlying object and works transparently
with other packages which support the
Common Python Interface for WCS,
allowing for a more flexible approach to the problem and avoiding the limitations
of the FITS WCS standard.
Low Level API is the original
astropy.wcs API and originally developed as
It ties applications to the
astropy.wcs package and limits the transformations to the three distinct
types supported by it:
Table lookup distortions as defined in the FITS WCS distortion paper.
Pixel Conventions and Definitions#
However, there’s a difference in what is considered to be the first pixel. The
High Level API follows the Python and C convention that the first pixel is
the 0-th one, i.e. the first pixel spans pixel values -0.5 to + 0.5. The
Low Level API takes an additional
origin argument with values of 0 or 1
indicating whether the input arrays are 0- or 1-based.
The Low-level interface assumes Cartesian order (x, y) of the input coordinates,
however the Common Interface for World Coordinate System accepts both conventions.
The order of the pixel coordinates ((x, y) vs (row, column)) in the Common API
depends on the method or property used, and this can normally be determined from
the property or method name. Properties and methods containing “pixel” assume (x, y)
ordering, while properties and methods containing “array” assume (row, column) ordering.
A Simple Example#
One example of the use of the high-level WCS API is to use the
pixel_to_world to yield the simplest WCS
with default values, converting from pixel to world coordinates:
>>> from astropy.io import fits >>> from astropy.wcs import WCS >>> 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) >>> w = WCS(f.header) >>> sky = w.pixel_to_world(30, 40) >>> print(sky) <SkyCoord (ICRS): (ra, dec) in deg (5.52844243, -72.05207809)> >>> f.close()
Similarly, another use of the high-level API is to use the
world_to_pixel to yield another simple WCS, while
converting from world to pixel coordinates:
>>> from astropy.io import fits >>> from astropy.wcs import WCS >>> 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) >>> w = WCS(f.header) >>> x, y = w.world_to_pixel(sky) >>> print(x, y) 30.00000214673885 39.999999958235094 >>> f.close()