Navigation

astropy.wcs contains utilities for managing World Coordinate System
(WCS) transformations in FITS files. These transformations map the
pixel locations in an image to their real-world units, such as their
position on the sky sphere. These transformations can work both
forward (from pixel to sky) and backward (from sky to pixel).

It performs three separate classes of WCS transformations:

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

This example loads a FITS file (supplied on the commandline) and uses
the WCS cards in its primary header to transform.

# Load the WCS information from a fits header, and use it# to convert pixel coordinates to world coordinates.importnumpyasnpfromastropyimportwcsfromastropy.ioimportfitsimportsysdefload_wcs_from_file(filename):# Load the FITS hdulist using astropy.io.fitshdulist=fits.open(filename)# Parse the WCS keywords in the primary HDUw=wcs.WCS(hdulist[0].header)# Print out the "name" of the WCS, as defined in the FITS headerprint(w.wcs.name)# Print out all of the settings that were parsed from the headerw.wcs.print_contents()# Three pixel coordinates of interest.# Note we've silently assumed a NAXIS=2 image herepixcrd=np.array([[0,0],[24,38],[45,98]],np.float_)# Convert pixel coordinates to world coordinates# The second argument is "origin" -- in this case we're declaring we# have 1-based (Fortran-like) coordinates.world=w.wcs_pix2world(pixcrd,1)print(world)# Convert the same coordinates back to pixel coordinates.pixcrd2=w.wcs_world2pix(world,1)print(pixcrd2)# These should be the same as the original pixel coordinates, modulo# some floating-point error.assertnp.max(np.abs(pixcrd-pixcrd2))<1e-6if__name__=='__main__':load_wcs_from_file(sys.argv[-1])

This example, rather than starting from a FITS header, sets WCS values
programmatically, uses those settings to transform some points, and then
saves those settings to a new FITS header.

# Set the WCS information manually by setting properties of the WCS# object.importnumpyasnpfromastropyimportwcsfromastropy.ioimportfits# Create a new WCS object. The number of axes must be set# from the startw=wcs.WCS(naxis=2)# Set up an "Airy's zenithal" projection# Vector properties may be set with Python lists, or Numpy arraysw.wcs.crpix=[-234.75,8.3393]w.wcs.cdelt=np.array([-0.066667,0.066667])w.wcs.crval=[0,-90]w.wcs.ctype=["RA---AIR","DEC--AIR"]w.wcs.set_pv([(2,1,45.0)])# Some pixel coordinates of interest.pixcrd=np.array([[0,0],[24,38],[45,98]],np.float_)# Convert pixel coordinates to world coordinatesworld=w.wcs_pix2world(pixcrd,1)print(world)# Convert the same coordinates back to pixel coordinates.pixcrd2=w.wcs_world2pix(world,1)print(pixcrd2)# These should be the same as the original pixel coordinates, modulo# some floating-point error.assertnp.max(np.abs(pixcrd-pixcrd2))<1e-6# Now, write out the WCS object as a FITS headerheader=w.to_header()# header is an astropy.io.fits.Header object. We can use it to create a new# PrimaryHDU and write it to a file.hdu=fits.PrimaryHDU(header=header)# Save to FITS file# hdu.writeto('test.fits')

Note

The members of the WCS object correspond roughly to the key/value
pairs in the FITS header. However, they are adjusted and
normalized in a number of ways that make performing the WCS
transformation easier. Therefore, they can not be relied upon to
get the original values in the header. To build up a FITS header
directly and specifically, use astropy.io.fits.Header directly.

Bounds checking is enabled by default, and any computed world
coordinates outside of [-180°, 180°] for longitude and [-90°, 90°] in
latitude are marked as invalid. To disable this behavior, use
astropy.wcs.Wcsprm.bounds_check.

As astropy.wcs is based on wcslib, it supports the standard
projections defined in the FITS WCS standard. These projection
codes are specified in the second part of the CTYPEn keywords
(accessible through Wcsprm.ctype), for
example, RA---TAN-SIP. The supported projection codes are:

AZP: zenithal/azimuthal perspective

SZP: slant zenithal perspective

TAN: gnomonic

STG: stereographic

SIN: orthographic/synthesis

ARC: zenithal/azimuthal equidistant

ZPN: zenithal/azimuthal polynomial

ZEA: zenithal/azimuthal equal area

AIR: Airy’s projection

CYP: cylindrical perspective

CEA: cylindrical equal area

CAR: plate carrée

MER: Mercator’s projection

COP: conic perspective

COE: conic equal area

COD: conic equidistant

COO: conic orthomorphic

SFL: Sanson-Flamsteed (“global sinusoid”)

PAR: parabolic

MOL: Mollweide’s projection

AIT: Hammer-Aitoff

BON: Bonne’s projection

PCO: polyconic

TSC: tangential spherical cube

CSC: COBE quadrilateralized spherical cube

QSC: quadrilateralized spherical cube

HPX: HEALPix

XPH: HEALPix polar, aka “butterfly”

And, if built with wcslib 5.0 or later, the following polynomial
distortions are supported:

TPV: Polynomial distortion

TUV: Polynomial distortion

Note

Though wcslib 5.4 and later handles SIP polynomial distortion,
for backward compatibility, SIP is handled by astropy itself
and methods exist to handle it specially.

astropy.wcs contains utilities for managing World Coordinate System
(WCS) transformations in FITS files. These transformations map the
pixel locations in an image to their real-world units, such as their
position on the sky sphere.

For a WCS returns pixel scales along each axis of the image pixel at the CRPIX location once it is projected onto the “plane of intermediate world coordinates” as defined in Greisen & Calabretta 2002, A&A, 395, 1061.