.. doctest-skip-all .. _astropy-wcs: *************************************** World Coordinate System (`astropy.wcs`) *************************************** .. _wcslib: http://www.atnf.csiro.au/~mcalabre/WCS/ .. _Paper IV: http://www.atnf.csiro.au/people/mcalabre/WCS/index.html .. _SIP: http://irsa.ipac.caltech.edu/data/SPITZER/docs/files/spitzer/shupeADASS.pdf .. _ds9: http://hea-www.harvard.edu/RD/ds9/ Introduction ============ `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. It is at its base a wrapper around Mark Calabretta's `wcslib`_, but also adds support for the Simple Imaging Polynomial (`SIP`_) convention and table lookup distortions as defined in WCS `Paper IV`_. Each of these transformations can be used independently or together in a standard pipeline. Getting Started =============== The basic workflow is as follows: 1. ``from astropy import wcs`` 2. Call the `~astropy.wcs.WCS` constructor with an `astropy.io.fits` header and/or hdulist object. 3. Optionally, if the FITS file uses any deprecated or non-standard features, you may need to call one of the `~astropy.wcs.wcs.WCS.fix` methods on the object. 4. Use one of the following transformation methods: - `~astropy.wcs.wcs.WCS.all_pix2world`: Perform all three transformations from pixel to world coordinates. - `~astropy.wcs.wcs.WCS.wcs_pix2world`: Perform just the core WCS transformation from pixel to world coordinates. - `~astropy.wcs.wcs.WCS.all_world2pix`: Perform all three transformations from world to pixel coordinates, using an iterative method if necessary. - `~astropy.wcs.wcs.WCS.wcs_world2pix`: Perform just the core WCS transformation from world to pixel coordinates. - `~astropy.wcs.wcs.WCS.sip_pix2foc`: Convert from pixel to focal plane coordinates using the `SIP`_ polynomial coefficients. - `~astropy.wcs.wcs.WCS.sip_foc2pix`: Convert from focal plane to pixel coordinates using the `SIP`_ polynomial coefficients. - `~astropy.wcs.wcs.WCS.p4_pix2foc`: Convert from pixel to focal plane coordinates using the table lookup distortion method described in `Paper IV`_. - `~astropy.wcs.wcs.WCS.det2im`: Convert from detector coordinates to image coordinates. Commonly used for narrow column correction. For example, to convert pixel coordinates to world coordinates:: >>> from astropy.wcs import WCS >>> w = WCS('image.fits') >>> lon, lat = w.all_pix2world(30, 40, 0) >>> print(lon, lat) Using `astropy.wcs` =================== Loading WCS information from a FITS file ---------------------------------------- This example loads a FITS file (supplied on the commandline) and uses the WCS cards in its primary header to transform. .. literalinclude:: examples/from_file.py :language: python Building a WCS structure programmatically ----------------------------------------- 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. .. literalinclude:: examples/programmatic.py :language: python Validating the WCS keywords in a FITS file ------------------------------------------ Astropy includes a commandline tool, ``wcslint`` to check the WCS keywords in a FITS file:: > wcslint invalid.fits HDU 1: WCS key ' ': - RADECSYS= 'ICRS ' / Astrometric system RADECSYS is non-standard, use RADESYSa. - The WCS transformation has more axes (2) than the image it is associated with (0) - 'celfix' made the change 'PV1_5 : Unrecognized coordinate transformation parameter'. HDU 2: WCS key ' ': - The WCS transformation has more axes (3) than the image it is associated with (0) - 'celfix' made the change 'In CUNIT2 : Mismatched units type 'length': have 'Hz', want 'm''. - 'unitfix' made the change 'Changed units: 'HZ ' -> 'Hz''. Bounds checking --------------- 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`. Supported projections ===================== As `astropy.wcs` is based on `wcslib`_, it supports the standard projections defined in the WCS papers. These projection codes are specified in the second part of the ``CUNITn`` keywords (accessible through `Wcsprm.cunit `), 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" Other information ================= .. toctree:: :maxdepth: 1 relax history See Also ======== - `wcslib`_ Reference/API ============= .. automodapi:: astropy.wcs Acknowledgments and Licenses ============================ wcslib is licenced under the `GNU Lesser General Public License `_.